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by Richard Gaskin 


As Mac OS development tools continue to evolve, there is one 
important category which is often overlooked in the Mac community: 
rapid application development (RAD). 

The availability of robust RAD tools for Windows, most notably 
Visual Basic, is arguably one of the primary contributors to the pletliora 
of new applications written for the Wintel platform, and absolutely critical 
to the entrenchment of Wintel in corporate and academic environments 
where custom applications need to be cranked out regularly. 

RAD tools represent a critical component of Mac evangelism as 
well, allowing opportunities for organizations to create custom solutions 
which fill market niches and keep folks using Macs. Apple has been 
proudly citing the number of new applications for Mac OS since the 
announcement of the iMac, but it seems a fair bet that this number 
would at least double if the company took a more active role in 
popularizing RAD tools for Mac OS. 

In recent years, developers on other platforms have seen an 
increased awareness of the value of scripting. As John Ousterhout of 
vScriptics Corporation put it in his seminal white paper “Scripting: 
Higher Level Programming for the 21st Century” 
<http://www.scriptics.com/people/john.ou5terhout/scripting.html>: 

Scripting languages and sy.stem programming languages are 
complementary, and iimst major computing platforms since the 1960’s 
have provided bolh kinds of languages. The languages are typically used 
together in component frameworks, where components are created with 
system programming languages and glued together with scripting 
languages. However, several recent trends, such as faster machines, 
better scripting languages, the increasing importance of graphical user 
interfaces and component architectures, and the growth of the Internet, 
have greatly increased the applicability of scripting languages. These 
trends will continue over the next decade, with more and more new 
applications written entirely in scripting languages and system 
programming languages used primarily for creating components. 

Many of the most popular scripting tools on other platforms were 
inspired by Apple's own HyperCard, including Asymetrix I'oolBook and 
Visual Basic. The attraction is easy to appreciate: by mariying a 
hierarchical GUI environment to an interpreted language which automates 
most memory management, development cycles can be slashed by orders 
of magnitude. Offering the same friendliness that is the essence of 
Macintosh, 1 lyperCard introduced programming for the rest of us. 

Ironically, while Apple has spent millions on since-abandoned efforts 
like Dylan and ScriptX, their most successful development tool, HyperCard, 
has never been enhanced l^eyond its monochrome architecture and may 
soon be axed <http://www.hyperactivesw.com/SaveHC.htnnl>. 

But in spite of Apple’s lack of serious commitment to HyperCard 
in recent years, other vendors have successfully expanded on the easy- 
to-learn language and are allowing people to develop solid Mac 


applications in record time for their organizations, and often for 
commercial di.stribution as well. 

Many folks have the impression that any xTalk language (the 
collective term for HyperTalk and related dialects) is unsuitable for 
serious development, but these perceptions have more to do with 
HyperCard’s implementation than any inherent problem with the 
language or object model. At least two other vendors have successfully 
enhanced xTalk in ways that are extremely potent for RAD work. 

For cross-platform deployment, MetaCard <www.metaard.com> offers a 
very similar object model as HypeiCarcl, but also offers multiple windows 
in different styles, integrated color, rich media support, and has one of the 
fastest inteipretei’s in the business. Being the only xlalk which allows 
authoring and deployment on all major platforms (Mac OS, Windows, and 
UNIX), 1 have found it to l:>e an excellent substitute for Java for many 
projects, allowing me to enjoy universal deployment at a fraction of the 
development time. And lx.'C'au.se .scripting is e.ssentially a shorthand glue 
Ixitween compiled routines in an inteipreter, many ojxjrations run 
noticeably faster in MetaCard ihm equivalent Java implementations. For GUI 
apps, MetaCard makes Java l(X)k like “write once, crawl anywhere”. 

To make truly Mac-like software quickly, there is no better product 
than SuperCard <www.incwell.com>. While SuperCard is currently only 
available for Mac OS, it offers many of the advantages of MetaCard but is 
unencumbered by cross-platform considerations. Like a .software glove 
wrapped around the Mac OS, SuperCard allows developers to take 
advantage of extremely modern Mac OS features such as the Appearance 
Manager, speech recognition, QTVR, and what is probably the world’s first 
scriptable control over OS-level drag-and-drop. Try implementing all of 
these in C++ in an afternoon.:) The aimor mill has it that the SuperCard 
team is working on a suite of tools aimed at professional developers which 
will include an API for accessing many of the program’s internal data 
staictures and routines. This would allow developers to use SuperCard as 
a form of precompiled application framework, in which the standard GUI 
stuff is handled in scripting while compulalionally-intensive routines can 
be easily integrated from custom C code. 

While there are limitations to developing with any 4GL, the 
advantages are compelling for many applications, especially those 
designed for vertical markets, schools, and smaller organizations 
where the greater costs of developing purely in C++ or Java would 
be prohibitive. In those formal languages, development time in 
measured in weeks and months, but in xTalk products the.se are often 
measured in days, or even hours. 

And even for projects based in C++, xTalk products provide all the 
ncces.sary ingredients for rapid prototyping, which can make a critical 
difference in early design and usability discussions. Apparently Microsoft 
agrees: If my sources are correct, even Visual Basic was first prototyped 
in SuperCard, on a Mac of course. :) Ml 


Richard Gaskin is the ambassador of Fourth World <http://www.fourthworld.com>, a Los Angelcs-based consultancy specializing in scripting 
languages for Mac, Windows, and UNIX. You can reach him at ambassador@fourthwoiid.com. 
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GETTING 

STARTED 


hy Dan Parks Sydow 


Carbon: Getting Ready for Mac OS X 


Becoming familiar with the 
Carbon API to ready your 
code for Mac OS X 


In the previous few months we’ve 
covered a variety of graphics-related 
programming topics, including bringing 
color and animation to your Mac 
programs. In future articles we’ll discuss 
other multimedia enhancements (such as 
sound-playing) that you can incorporate 
into your own code. This month, however, 
we’ll take a pause in tlie multimedia action 
to look at what is Ix^coming a very 
important topic to all Mac programmers: 
Mac OS X and the Carbon application 
programming interface. 

Apple will seed the beta version of 
Mac OS X to select developers next month. 
Some of you readers may be in the group 
lucky enough to be getting your hands on 
a copy of the new, modern operating 
system. But even if you won’t be getting a 
sneak-peek at Mac OS X, tliere are still 
plenty of things you can do to ensure that 
your own program — whether trivial or 
all-powerful — is ready for the prime-time 
release of Mac OS X later this year. 

Aboui Mac OS X 

By now you’ve certainly read 
numerous magazine columns, online 
reports, and even newspaper articles, 
devoted to Mac OS X. So we can be 
succinct here in our definition of just what 
Mac OS X is. Mac OS X is the version of the 
Macintosh operating system that’s to bring 
about the important new features and 
enhancements that all developers and 


many users have clamored for. Applications ainning in Mac OS X 
will have a number of advantages over applications auining in 
previous versions of the Mac OS X. In short, these advantages are: 

Increased stability A protected address space means memoiy 
protection. When a program “goes bad” it may crash, but it won’t 
lake down other applications or crash the system. 

Increased responsiveness Preemptive multitasking means 
that the processor is l)eiier able to service all ainning applications, 
resulting in each application lx:ing more responsive. 

Dynamic resource allocation Applications use system 
resources (such as memory) as needed — they don’t need to 
specify and adhere to predetermined values. 

Okay, Mac OS X sounds pretty cool — users will really 
experience faster applications and fewer crashes. But what do 
these enhancements mean for us programmers? Tlie answer to 
that question is the basis of this article, so read on! 

About Carbon 

API stands for application programming interface, and it’s 
the means of helping programmers develop applications that 
make use of, or interface with, the code that comprises the 
operating system. Each operating system has its own API, so to 
make it quickly evident which API a programmer is referring to, 
each API has a name. As you know from reading Getting Started, 
the API Macintosh programmers use is referred to as the 
Macintosh Toolbox (or the Mac Toolbox, or simply the Toolbox). 
The Macintosh Toolbox, like any API, is nothing more than a set 
(albeit a very large set) of routines. When you learn how to make 
use of these routines, you know how to write programs. 

Mac OS X will intrcxjuce a host of changes to the Macintosh 
operating system, so a new means of allowing programmers to 
interface with the OS is needed. Carbon is that meaas. Carlxm, like 
the Toolbox, is the set of programming interfaces a programmer 
uses to develop Macintosh applications. Specifically, Carbon is the 
set of routines programmers use to develop Mac OS X applications 
that can also run on Mac OS 8. When a programmer writes a 
program using Carbon, tliat program takes advantage of the 
features new to Mac OS X, such as preemptive multitasking, 
memory protection, and dynamic resource allocation. 

What happens when you run a “carbonized” application on 
a Mac hosting Mac OS 8 rather than on a Mac hosting Mac OS 
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Ii will run just fine. It won’t, however, be more responsive or 
more stable than any other Mac OS 8 application. Mac OS 8 will 
simply consider it another Mac OS 8 application. Copy dial same 
application to a Mac hosting Mac OS X, though, and the 
carbonized program will exhibit the traits expected of a Mac OS 
X application. To summarize: 

Macintosh Toollxix llie API for developing applications that 
run on a Macintosh computer hosting any version of the Mac OS 
prior to Mac OS X (such as Mac OS 8.5, Mac OS 7.6, and so forth). 

Carlxin The API for developing applications that can run on a 
Macintosh computer hosting Mac OS X or any version of Mac OS 8. 

Learning a new API can be a daunting task. If you’re a 
regular reader of Getting Started, you are probably just 
beginning to feel comfortable with using the Macintosh Toolbox 
API. If tomorrow you were asked to develop a program that 
would run on a PC hosting Windows 95 or Windows 98, you’d 
have your work cut out for you. While some general 
programming principles would translate from one operating 
system to the other, your API knowledge would be all but 
useless — Windows has its own huge .set of API routines that a 
programmer uses to develop a Windows application. 'Phis all 
sounds pretty ominous, but it isn’t. It’s just a setup to let you 
know how easy you, the Mac programmer, has it. Why? Because 
the transition from the Macintosh T(K)lbox API to the Carbon API 
is nothing like the transition from the Macintosh API to the 
Windows API. This is because Carbon is nothing more than a 
cleaned-up, cniianced, Macintosh Toolbox. If you’re familiar 
with the Macintosh 1‘oolbox, you’re familiar with Carton. 'Phe 
more you already know about tlie Macintosh 'Pooltox, the more 
you will know atout Carbon. 

When Apple bought NeXT, they obtained OpenStep — the 
API that NeX'P programmers use to write applications that run on 
a computer hosting the NeXT operating system. Just as a Mac 
programmer makes use of the Toolbox API (and soon, tlie 
Carbon API) when developing a Macintosh application, a NeXT 
programmer makes u.se of the OpenStep API when developing 
a NeXT application. After acquiring NeXT, Apple set about 
adding to OpenStep — Apple engineers wrote new code to 
enhance the existing OpenStep code. To distinguish this 
‘'enhanced OpenStep” from the original OpenStep, Apple gave 
the new API a new name: Yellow Box. Like Carbon, the Yellow 
Box is an API used to develop applications that will nin on Mac 
OS X. LJnlike Carbon, the Yellow Box isn’t similar, or based on, 
the Macintosh Toolbox (because its origin is a different 
0 [>erating system — the NeXT operating system). 

'Phe disadvantage to developing with the Yellow Box is 
readily apparent: a Mac programmer needs to learn a completely 
new API. The advantage to developing with the Yellow Box, 
though, can be impressive: applications based on the Yellow 
Box API are cross-platform. An application developed using the 
Yellow Box will, without modification, run on a Macintosh 
hosting Mac OS X. It will also run on a PC running Yellow Box 
for Windows — the Apple software that can be installed on most 
PCs running Windows 95 or Windows 98. When a PC user has 
Yellow Box for Windows on his Wintel computer, his machine 


can run all liis Windows applications and any Mac OS X 
application developed using the Yellow Box API. 

Programming with the Yellow Box API is out of the scope 
of Getting Started — here we’ll stick to the tried-and-true 
Macintosh Toolbox and its .siicces.sor, Carbon. Look for a number 
of Yellow Box articles in other areas of upcoming issues of 
MacTech Magazine. 

Preparin(; For Carbon 

Mac OS X isn’t here yet, and the Carbon Aid isn’t finalized 
either. But of course we won’t let those minor obstacles prevent 
us from getting started programming for Mac OS X! Even without 
a final version of Carbon available, you can write Carbon- 
compliant code. Carbon-compliance means: 

Compilation Your code successfully compiles when using 
the .same universal interface files that will be used for creating 
Mac OS X applications. 

Mac OS X and Mac OS 8 compatible The resulting 
application runs on both Mac OS 8 and Mac OS X. 

Mac OS X enhanced 'Phe resulting application takes 
advantage of Mac OS X features such as preemptive multitasking 
when running on Mac OS X. 

Using tiie Universal Interface Header Files 

One step in the preparation for Carbon is to obtain and use 
the most recent version of the universal header files. These 
interface files provide your projects with the latest function 
prototypes for all of the Ibolbox functions. As Apple alters 
T(X)lbox functions for Carbon, the changes will be reflected in 
the function prototypes in the universal header files. These 
interface files are always available to programmers through 
Apple’s public Web site — go to Apple’s Carbon Web site at 
<http://gemma.apple.com/macosx/carbon/> to find the link that 
lets you download the whole set. 

When you installed Code Warrior on your hard drive, the 
installer copied the universal header files from the install CO to 
a folder named Universal Headers in the Headers folder — the 
full path from inside your main CodeWarrior folder is 
Metrowerks CodeWarrior:MacOS Support:!leaders:Universal 
Headers. Replace this Universal Header folder with the newly 
downloaded folder of the same name (you can always return to 
using the original set by copying the universal header files from 
the CodeWarrior install CD). 

CodeWarrior projects typically make use of the universal 
header files by including one of the compiled Mad leaders 
libraries (they reside in the MacHeaders folder, which from your 
main CodeWarrior folder has a path of Metrowerks 
CodeWarrior:MacOS Support:MacHeader.s). To get your projects 
to make use of die new universal header files you’ll need to 
recompile the various MacHeader libraries. CodeWarrior comes 
with an ApplcScTipt that takes care of that task for you — from 
die AppleScript menu of the CodeWarrior IDE choose Recompile 
MacHeaders. If the IDE isn’t displaying die AppleScript menu, 
check the Use Script menu checkbox from the IDE Extras panel 
in the IDE’s preferences window (choose Preferences from the 
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Edit menu). Once the AppleScript executes, the Mactieaders 
libraries will [)e updated and your existing and new projects will 
make use of them without any extra effort on your part. 

Become Famiuar With Fundamental Toolbox Differences 

llie Mac OS X application model and the Mac OS 8 
application model are essentially the same. Each type of 
program is centered on an event loop tliat calls WaitNextEventO 
to procure events from the event queue, and each type of 
program uses Human Interface routines from the 'Foolbox to add 
and support interface elements such as menus and windows. 
Mac OS X and Mac OS 8 do differ enough from one another in 
that programs won’t access system services in identical manners, 
tliough. Here are a few of the noteworthy differences. 

Human Interface Toolbox 'Ihis is the part of the Macintosh 
Toolbox that consists of a group of routines that implement the 
Mac OS human interface. Menu, window, and dialog box 
routines are all found here. For the most part, the Human 
Interface TckJIx)x is supported. 'Fhe major exception is that the 
Standard File Package will not be supported. Instead, Mac OS X 
will rely on Navigation Services. Read more about Navigation 
Services in the August 1998 issue of MacTech Magazine (Vol.l4, 
No.9) and in the Programmer’s Introduction to Mac OS 8.5 article 
in the November 1998 MacTech Magazine i.ssue (Vol.l4, No. II). 

Application Utilities This area of the Macintosh TcK)lbox 
holds the routines that extend the human interface. Apf)le Guide 
and the Drag Manager fall into this group. Mac OS X promises 
to support most of these utilities. One possible exception is the 
Speech Manager — Apple hasn’t come to a final decision as to 
whether the Speech Manager routines will remain supported. 

Graphic Services The Macintosh Toolbox functions that are 
thought of as graphic services routines are the ones that allow your 
program to display images. QuickDraw GX won’t be supported in 
Carbon, but the more popular QuickDraw and QuickDraw 3D 
managers will lie supported. Color QuickDraw, the topic of 
Getting Started two issues back, will also be suji|xirted. 

Multimedia Services QuickTime is the most popular means 
of getting multimedia effects into a Macintosh program. 
QuickTime will be fully supported in Qtrlxm. 

Low-Level Operating System Services Designing and 
implementing an application’s user-interface is enjoyable 
because you get visual feedback of your efforts. But the low- 
level OS services, such as memory management and file 
handling, are equally im|X)rtant. Carbon will support most of 
these services, but expect some reworking of your source code. 
Memory management in Mac OS X will differ from Mac OS 8, so 
flag (comment) any memory management code in your projects 
to remind you that changes may be in order. The same applies 
to your project’s file handling code. Most file handling code will 
work as is, but the infonnation necessary to define a file system 
specification (an FSSpec variable) will need to be more complete 
than in the past. Future Getting Started columns will tackle a 
couple of often-neglected low-level services: memory 
management and file handling. 


Testing For Carbon Compatibb ity 

Apple is going through the Macinto.sh T(K)lbox and 
determining which of tlie thousands of routines should lx.* cut, 
which should stay in an unaltered state, and which should stay 
but undergo changes. You can find out the status of any Toolbox 
routine by clicking on the Carbon Specification link at 
<http://gemma.apple.com/macosx/carbon/>. Using this method to 
check the Carlx:>n-compatibility of each T(X)lbox routine your 
application calls would be a laborious process, so Apple’s come 
up with a software tool that automates the operation. The 
Carbon Dater application, freely available from Apple at 
<http.7/developer.apple.com/macosx/>, helps you determine the 
amount of effort you’ll need to expend to port a Macintosh 
application to Mac OS X. 

The Carbon Dater Analyzer 

The Carbon Dater analyzer pn)gram examines any PowerPC 
a|)plication and generates an output file tliat can be further 
exiimined for Qirlx)n-cx)mpatibility. You email tliis output file to 
Apple, and Apple then analyzes its contents and letums via email a 
final compatibility report in HTML fonnat. The pixxess is automated 
and fast — you may have your report back within tlie hour! 

The Analyzer Report 

The output data file created by the Carbon Dater program 
is an interim file — it alone isn’t helpful to you. Instead, you 
want to read Apple’s Carbon-compatibility report that gets 
generated from the interim Carbon Dater file. 

Apple’s report lists a number of potential pitfalls that you 
should watch for in writing code that you want to run on Mac 
OS X. Mo.st importantly, the report examines all the 'Ibolbox 
functions your code accesses and determines which calls you 
need to update or replace. Every que.stionable Toolbox call 
your application makes is mentioned in the report. Specifically, 
the report tells whether a questionable function is supported 
but modified, unsu[)ported, under evaluation (as to whether it 
will be supported), or doesn’t exist in the latest version of the 
universal header files. 

As shown later in this article, the report includes a pie chart 
that shows the percentages of T(X)lbox calls that fall into each 
category. In addition to alerting you to cjuestionable calls, the 
report may provide solutions that seiYe as workarounds. 

Carbon Dating Some 0)de 

You can nin any PowerPC code you want through the 
Carbon Dater, but until you’re familiar with the Carbon Dating 
process, it makes sense to avoid working with a monolithic 
a[)|)lication. Instead, make your initial test one that uses a 
relatively trivial program. Choose your own simple application, 
or pick any of tlie examples from previous Getting Started 
columns. For no particular reason we’ll look over the PixMapper 
example from last month’s Getting Started. You can download 
that code (or any other [)ack-issue code) from the MacTech ftp 
site at <ftp://ftp.mactech.com/src/>. 
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heaviest traffic in San Francisco 
and loving every minute of it. 


This year at Macworld Expo, AppleR is going to make it easier for all developers, 
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Running the Carbon Dater 
The Carbon Dater only works with PowerPC-native 
applications, so set your CodeWarrior project to generate a 
PowerPC or fat application and then build an application. 
From the desktop open the Carbon Dater folder and drag 
your application’s icon onto the Carbon Dater icon. When 
you do that, the Dater goes to work. As shown in Figure 1, 
the Carbon Dater posts a window that provides you with a 
little feedback as to what the analyzer is doing. 



FilerPixMapper 

Status: Processing Function Data 



Figure 1. The Carbon Dater in action. 


When the Carbon Dater is finished, you’re prompted to 
enter your email address. IT is address should represent the 
address you want Apple’s final report to be sent to, and will 
be embedded in the Carbon Dater output file. Figure 2 
shows this prompt. 


After you dismiss the email dialog box, the program 
responds by telling you where to email the Carbon Dater 
output file. Figure 3 shows that the output file will be your 
program’s name with the extension .CCT appended to it, and 
that this file goes to CarbonDating@apple.com. 


o 

Send the data file "PixMapper.CCT" 

—> as an email attachment <— 
to CarbonDating@appie.com to receive the 


finished compatibility report. 



Figure J. Getting a reminder as to what to do with the 
Carbon Dater output file. 


With the initial analysis complete, it’s time to give Apple 
the opportunity to provide you with the final decision on the 
Carbon-compatibility of your code. Launch your email 
application of choice, create a new mail message, and 
address it to CarbonDating@apple.com. Find the .CCT data 
file on your hard drive and add it to the message as an 
attachment. While it may not always be necessary, Apple 
recommends that you send the .CCT file as a stuffed file. If 
your email program supports stuffing, enable that feature to 
place the .CCT file in a Stufflt archive. If your email program 
won’t do that for you, use one of Aladdin’s programs, such 
as Stufflt or DropStuff, to stuff the .CCT file and then attach 
it to the email message. The message subject and body will 
be ignored, so at this point you’re all set to send the message 
off to Apple. 

'fhe chief responsibility of the Carbon Dater is to extract 
the names of the Toolbox rotitines your application calls. 
That information goes into the .CCT data file produced by 
the Carbon Dater. Apple’s job is to look over the contents of 
the .CCr file, create a final report, and email that report to 
the address you specified when you ran the Carbon Dater. 
These tasks are all automated, so after emailing the .CCT file 
to Apple, expect a returned report within an hour or so. 

Looking Over the Report 

Apple’s report to you will be in the form of an HTML file — 
open it witli any browser. Tlie report Ix^gins with a summary like 
the one shown in Figure 4. Tliis figure shows that tlie PixMapper 
program Is over ninety percent Carlxin-compliant. Apple has gone 
to great lengtlis to ensure tliat porting existing Mac OS 8 ccxie to Mac 
OS X code is as painless as po.ssible, so unless your code performs 
exotic, non-recommended tricks, it ux) should l^e veiy compliant. 



Figure 4. Looking over the final Carbon-compatibility report. 


The report’s summary shows that PixMapper includes 
calls to four questionable Toolbox functions. The next two 
paragraphs are what the report has to say about one of the 


Your email address: 




dan@sydow.com 



( Cancel ) 1 

o 

u 


Figure 2, Telling Apple where to send the report. 
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three routines that fall into the Supported But Not 
Recommended category: 

Carbon will support the Dialog Manager. However, 
Apple encourages you to ensure that your application 
accesses Dialog Manager data structures only through the 
supplied accessor functions. I'he use of these accessor 
functions, to be provided soon, will give your application 
greater threading flexibility in Mac OS X. Furthermore, you 
are encouraged to use the functions provided for creating 
and disposing of Dialog Manager data structures. In Mac OS 
X, applications might not be allowed to create and dispose 
of Dialog Manager data structures except by calling Dialog 
Manager functions. 

InitDialogs InitDialogs does nothing. There is no need to 
initialize the Window Manager, because the shared library 
gels loaded as needed. 

FixMapper’s call to TnitDialogsO is flagged because the 
call won’t be necessary in Mac OS X applications. 'Fhe Dialog 
Manager won’t need to be initialized because in Mac OS X its 
code gets loaded into memory. A Mac application can still 
make the call, but it will be unnecessary. 

Just before the information on InitDialogsO, the report 
includes information regarding Carbon’s support of the 
Dialog Manager. Don’t be alarmed by these “warnings” that 
appear throughout the report — they may or may not apply 
to your code. Each modified or unsupported Toolbox routine 
that your program makes generates a short, general essay on 
the Carbon-compatibility of the manager the routine belongs 
to. So while PixMapper doesn’t make any serious Dialog 
Manager mistakes, the report still includes Dialog Manager 
information (because of the call to the unsupported Dialog 
Manager routine InitDialogsO). In short, we’re being 
reminded to stick to using the Toolbox when working with 
dialog boxes. We shouldn’t try to circumvent Apple’s way of 
doing things by developing our own routines to access fields 
of a dialog record. As a Getting Started reader you know we 
try to stick to doing things by-the-book, and certainly would 
never try tricks like that! 

Now let’s see some of what the report has to say about 
PixMapper’s one call to an unsupported Toolbox function: 

In Mac OS X, code that conmiunicates directly with 
hardware devices must use the lOKit API. Other types of code 
that have relied on the Device Manager interface In the past (such 
as desk accessories) should be converted into applications. 

OpenDeskAcc Desk accessories will not be supported in 
Carbon. A new mechanism will be provided for handling 
selections from the Apple menu. 

I'he lOKit is new, and particular to, Mac OS X. I'here is 
no comparable Mac OS routine set. 'fhe comment says that 
the concept of desk accessories is being abandoned (it has 
been, by the way, unofficially abandoned for awhile now). 
The OpenDeskAccO routine — which we’ve been using in 
our examples to open any item in the Apple menu, won’t be 
supported in Carbon. No replacement routine is mentioned 


in the report, but at least now we know what code is subject 
to change. We can’t immediately correct the potential 
problem, but as shown in Figure 5 we can go back into the 
PixMapper.c file and add a comment to serve as a reminder 
of what needs updating in the PixMapper code. 



Figure 5. Flagging code for future changes. 

After looking over tlie re[)ort you’ll be able to at best make 
the necessary code changes, and at worst mark the potential 
problem areas for future alterations. In all cases you’ll be closer 
to being Mac OS X ready. 

Till Next Month... 

Apple’s Mac OS X plan is clear: provide the user with a 
faster, more stable computing environment, and provide 
developers with a straightforward, short learning-curve way 
of getting the user there. The Mac OS X operating system is 
for the Macintosh user. Carbon is for you, the Macintosh 
programmer. Starting now, you’ll want your code to be 
Carbon-compliant. 

Now that you’ve seen how to Carbon date your code, do 
it! Don’t stop at one test, Carbon date any programs to which 
you have the source code. It’s reassuring to see returned 
reports that show your code to be very Carbon-compliant, 
but it’s a good learning experience to get back a bad report 
too! Try to find out just what kind of code isn’t acceptable for 
the development of a Carbon-compliant application so that 
you’ll be truly ready for Mac OS X. 

Previous Getting Started articles each included a short 
example program — this month’s column didn’t. Next month 
we’ll return to our regular format of presenting a basic 
programming topic supplemented by a short, to-the-point, 
code example. As usual, the emphasis will be on Toolbox 
basics. However, now you know that what we’ve referred to 
in the past as Toolbox basics will subsequently be referred to 
as Carbon basics! See you next month... gj 
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POWER 

GRAPHICS 


by Ed Angel, University of New Mexico 


OpenGL for Mac Users: Part 2 


Advanced capabilities: 
architectural features and 
exploiting hardware 


iNTRODUCnON 

In Part 1, we developed the basics 
of OpenGL and argued that the OpenGL 
API provides an efficient and easy to use 
interface for developing three- 
dimensional graphics applications. 
However, if an API is to be used for 
developing serious applications, it must 
be able to exploit modern graphics 
hardware. In this article, we shall 
examine a few of the advanced 
capabilities of OpenGL. 

We shall be concerned with three 
areas. First, we sliall examine how to 
introduce realistic shading by defining 
material properties for our objects and 
adding light sources to the scene, 'fhen we 
shall consider the mixing of geometric and 
digital techniques afforded by texture 
mapping. We shall demonstrate these 
capabilities tlirough the color cube example 
that we developed in our first article. We 
will then survey some of the advanced 
features of OjxmGL, concentrating on three 
areas: writing client-server programs for 
networked applications, the use of OfX^nGL 
buffers, and the ability to tune performance 
to available hardware. 

Figure 1 is a more detailed view of 
the pipeline model that we introduced 


in Part 1. Geometric objects such as polygons are defined by 
vertices that travel down the geometric pipeline while 
discrete entities such as bits and picture elements (pixels) 
travel down a parallel pipeline. The two pipelines converge 
during rasterization (or scan conversion). Consider what 
happens to a polygon during rasterization. I'irst, the rasterizer 
must compute the interior points of the polygon from the 
vertices. 'I’he visibility of each point must be determined 
using the z or depth buffer that we discussed in Part 1. If a 
point is visible, then a color mu.st be determined for it. In the 
simple model that we used in Part 1, a color either was 
assigned to an entire polygon or was interpolated across the 
polygon using the colors at the vertices. Here we shall 
consider two other possibilities that can be used either alone 
or together. We can assign colors based on light sources and 
material properties that we can assign to the polygon. Second 
we can use the pixels from the discrete pipeline to determine 
or alter the color, a process called texture mapping. Once a 
color has been determined, we can place the point in the 
frame buffer, place it in one of the other buffers, or use the 
other buffers and tables to modify this color. 



Figure L Pipeline Model. 


In Part 1, we developed a sequence of programs that 
displayed a cube in various ways. These programs 
demonstrated the structure of most OpenGL programs. We 
divided our programs into three parts. 'Fhe main function sets 
up the OpenGL interface with the operating system and defines 
the callback functions for interaction. It will not change in our 
examples here. The myinit function defines user p>ararneters. 


Ed Angel is a Professor of Computer Science and Electrical and Computer Engineering at the University of New Mexico. He 
is the author of Interactive Computer Graphics: A top-down with OpenGL (Addison-Wesley, 1997). You can find out more 
about him at w'ww’.cs.unm.edu/~angel or write him at angel@cs.unm.edu. 
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panel provides complete remote 
control over your network databases. 
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■ 100 MB Searchable Blobs 

■ Database Replication 

Server Platforms 

■ Mac OS X 

■ Solaris_ 
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OpenBase^ 


The display callback typically contains the graphical objects. 
Our examples here will modify these two functions. 

Lights and Materials 

In simple graphics applications, we assign colors to lines and 
polygons tliat are used to color or shade the entire object. In the 
real world, objects do not appear in constant colors. Rather colors 
change gradually over surfaces due to the interplay lx.*tween the 
light illuminating the surface and the absorbtion and scattering 
properties of the surface. In addition, if the material is shiny such 
as a metallic surface, the location of the viewer will affect what 
shade she sees. Although physically-based models of these 
phenomena can be complex, there are simple approximate 
models that work well in most graphical applications. 



Figure 2. The Phong Shading Model. 


OpenGL uses the Phong shading model, which is based on 
the four vectors shown in Figure 2. Light is assumed to arrive 
from either a point source or a source located infinitely far from 
the surface. At a point on the surface tlie vector L is the direction 
from the point to the source. The orientation of the surface is 
determined by the normal vector N. Finally, the model uses the 
angle of a perfect reflector, R, and the angle between R and the 
vector to the viewer V. The Phong model contains diffuse, 
specular, and ambient terms. Diffuse light is scattered equally in 
all directions. Specular light reflects in a range of angles close to 
tlic angle of a perfect reflection, while ambient light models the 
contribution from a variety of sources and reflections too complex 
to calculate individually. The Phong model can l)e computed at 
any point where we have the required vectors and the local 
absorbtion coefficients. For polygons, OpenGL applies the model 
at the vertices and computes vertex c:olors. To color (or shade) a 
vertex, we need the normal at the vertex, a set of material 
properties, and the light sources that illuminate that vertex. With 
this information, OpenGL can compute a color for the entire 
polygon. For a flat polygon, we can simply assign a normal to the 
first vertex and let OpenGL use the computed vertex color for the 
entire face, a technique called flat shading. If we want the 
polygon to appear cuived, we can assign different normals to 
each vertex and then OpenGL will interpolate the computed 
vertex colors across the polygon. Tills later method is called 
smooth or interpolatwe shading. For objects composed of flat 
polygons, flat shading is more appropriate. 
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Let’s again use the cube with the vertex numbering in 
Figure 3- We use the function quad to describe the faces in 
terms of the vertices 


Listing 1: quad.c 

GLfloat vertices[8][3J = {{-1.0,-1.0,-1.0), (1.0.-1.0.-1.0}. 
(- 1 . 0 . 1 . 0 .- 1 . 0 ), ( 1 . 0 , 1 . 0 ,- 1 . 0 ),(- 1 . 0 ,- 1 . 0 , 1 . 0 ). 
( 1 . 0 ,- 1 . 0 , 1 . 0 ).(- 1 . 0 , 1 . 0 . 1 . 0 }.( 1 . 0 . 1 . 0 . 1 . 0 }); 

void quad(int a, int b, int c. int d) 

{ 

glBegin(GL_QUAD) 

glVertex3fv(vertices[a]); 
glVertex3fv(vertices[b]); 
glVertex3fv(vertices[c]); 
glVertexSfv(vertices[d]): 
glEndO: 


6 



To flat shade our cube, we make use of the six normal vectors, 
each of which points outward from one of the faces. Here is the 
modified cube function 


Listing 2: Revised cube.c with normals for shading 

Glfloat face_norinals[6] [3] ' ( 1.0.0.0,0.0). (0.0,-1.0, 0.0), 
( 0 . 0 . 0 . 01 . 0 ).( 1 . 0 . 0 . 0 . 0 . 0 ).( 0 . 0 . 1 . 0 . 0 . 0 ). 10 . 0 . 0 . 0 . 1 . 0 )); 

void cubeO 
( 

glNorinal3fv(face normals [2]); 
quad(0. 2. 3, 1); 
glNormal3fv(face_normals[4]); 
qiiad(2. 6. 7. 3); 
glNormal3fv(face_normals[Oj): 
quad(0. 4. 6. 2): 
giNonnai3fv(face_normals[3]); 
quadd. 3. 7, 5); 
glNormal3fv(face normals[5]); 
quad(4, 5, 7, 6); 
glNormal3fv(facc_normals[1]); 
quad(0. 1, 5, 4); 


Now that we have specified the orientation of each face, 
we must describe the light source(s) and the material 
properties of our polygons. We must also enable lighting and 
the individual light sources. Suppose that we recjuire just one 


light source. We can both describe it and enable it within 
myinit . OpenGL allows each light source to have separate 
red, green and blue components and each light source 
consists of independent ambient, diffuse and specular 
sources. Each of these sources is configured in a similar 
manner. For our example, we will assume our cube consists 
of purely diffuse surfaces, so we need only worry about the 
diffuse components of the light source. Here is a myinit for a 
white light and a red surface: 

Listing 3: Revised myint.c with lights and materials 

void myinit0 
( 

Glfloat mat_diffuse[j=*{1.0, 0.0, 0.0, 1.0); 

Glfloat light_diffused“(1.0, 1.0, 1.0, 1.0); 

Glfloat light0_pos[4] = ( 0.5. 1.5. 2.25, 0.0 ); 

glLightfv(GL_lTGHT0. GL.DIFFUSE, light_diffuse); 
glLightfv(GL_LIGHT0. GL_P0SIT10N, light0_pos): 

r define material properties for front face of all polygons 7 

glMaterialfv(GL_FRONT, GL_DIFFUSE, mat_diffuse); 

glEnable (GI._LTGHTTNG); r enable Ughting V 

glEnable(GL_LIGHT0); /* enable light 0 7 

glEnable (Gl_DEFTH_TEST); /* Enable liiddcn—surface—removal 7 
glClearColord .0, 1.0, 1.0, 1.0); 


Both the light source and the material have RGBA 
components. The light source has a position in four¬ 
dimensional homogeneous coordinates. If the last 
component is one, then the source is a point source located 
at the position given by the first three components. If the 
fourth component is zero, the source is a distant parallel 
source and the first three components give its direction. This 
location is subject to llie same transformations as are vertices 
for geometric objects. Figure 4 shows the resulting image 



Figure 4 Red Cube unth Diffuse Reflections. 


Texture Mapping 

While the capabilities of graphics systems are measured 
in the millions of shaded polygons per second that can be 
rendered, the detail needed in animations can require much 
higher rates. As an alternative, we can “paint” the detail on a 
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smaller number of polygons, much like a detailed label is 
wrapped around a featureless cylindrical soup can. Thus, the 
complex surface details that we see are contained in two- 
dimensional images, rather than in a three-dimensional 
collection of polygons. This technique is called texture 
mapping and has proven to be a powerful way of creating 
realistic images in applications ranging from games to movies 
to scientific visualization. It is so important that the required 
texture memory and mapping hardware are a significant part 
of graphics hardware boards. 

OpenGL supports texture mapping through a separate 
pixel pipeline that processes the required maps. Texture 
images (arrays of texture elements or texels) can be 
generated either from a program or read in from a file. 
Although OpenGL supports one through four-dimensional 
texture mapping, to understand the basics of texture 
mapping we shall consider only two-dimensional maps to 
three-dimensional polygons as in Figure 5. 



Figure 5. Texture Mapping a Pattern to a Surface. 


We can regard the texture image as continuous with two- 
dimensional coordinates 5 and t. Normally, these coordinate 
range over (0,1) with the origin at the bottom-left corner of 
the image. If we wish to map a texture image to a three- 
dimensional polygon, then the rasterizer must match a point 
on the polygon with both a point in the frame buffer and a 
point on the texture map. The first map is defined by the 
various transformations that we discussed in Part 1. We 
determine the second map by assigning texture coordinates 
to vertices and allowing OpenGL to interpolate intermediate 
values during rasterization. We assign texture coordinates via 
the function glTexCoord which sets up a present texture 
coordinate as part of the graphics state. 

Consider the example of a cjuadrilateral. If we want to map 
the entire texture to this polygon, we can assign the four corners 
of the texture to the vertices 


Listing 4: Assigning texture coordinates 

glRegin{GL_QUADS); 

glTexCoord2f(0.0. 0.0); 
glVertex3fv(a); 
gITexCoord2f(1.0. 0.0): 
glVertex3fv(b); 
glTexCoord2f(1.0, 1.0); 
glVertGx3fv(c); 
glTexCoord2f(0.0, 1.0); 
glVcrtcx3fv(d); 
glErid (); 

Figure 6 shows a checkerboard texture mapped to our 
cube. If wc assign the texture coordinates over a smaller 
range, we will map only part of the texture to the polygon 
and if we change the order of the texture coordinates we can 
rotate the texture map relative to the polygon. For polygons 
with more vertices, the application program must decide on 
the appropriate mapping between vertices and texture 
coordinates, which may not be easy for complex three- 
dimensional objects. Although OpenGL will interpolate the 
given texture map, the results can appear odd if the texture 
coordinates are not assigned carefully. The task of mapping 
a single texture to an object composed of multiple polygons 
in a seamless manner can be very difficult, not unlike the real 
world difficulties of wallpapering curved surfaces with 
patterned rolls of paper. 

Like other OpenGL features, texture mapping first must be 
enabled (glEnable(GL_TEXTURE)). Although texture mapping 
is a conceptually simple idea, we must also specify a set of 
parameters that control the mapping process. The major 
practical problems with texture mapping arise because the 
texture map is really a discrete array of pixels that often come 
from images. How these images are stored can be hardware 
and application dependent. Usually, we must specify explicitly 
how the texture image is stored (bytes/pixel, byte ordering, 
memory alignment, color components). Next we must specify 
how the mapping in Figure 5 is to be carried out. The basic 
problem is that we want to color a point on the screen but this 
point when mapped back to texture coordinates normally 
does not map to an s and / corresponding to the center of a 
texel. One simple technique is to have OpenGL use the closest 
texel. However, this strategy can lead to a lot of jaggedness 
(aliasing in the resulting image. A slower alternative is have 
OpenGL average a group of the closest texels to obtain a 
smoother result. I’hese options are specified through the 
function glTexParameter. Another issue is what to do if the 
value of s or t is outside the interval (0,1). Again using 
glTexParameter, we can either clamp the values at 0 and I or 
use the range (0,1) periodically. 'I’he most difficult issue is one 
of scaling. A texel, when projected onto the screen, can be 
either much larger than a pixel or much smaller. If the texel is 
much smaller, then many texels may contribute to a pixel but 
will be averaged to a single value. This calculation can a very 
time consuming and results in the color of only a single pixel. 
OpenGL supports a technique called mipmapping that allows 
a program to start with a single texture array and form a set of 


January 1999 • MaUTech 


OpenGL for Mac Users: Part 2 


15 
















smaller texture arrays that are stored. When texture mapping 
takes place, the appropriate array — the one that matches the 

si7:e of a texel to a pixel-is used. The following code sets 

up a minimal set of options for a texture map and defines a 
checkerboard texture. 


listing 5: inininium texture map setup in myintc 

void myinit0 
I 

GLubyte image[64][64][3]; 
int i, j, c; 

for(i=0 ;i<64;i++) for(j=0;j<64;j+f) 

{ 

/* Create an 8 x 8 checkerboard image of black and white texels V 
c = ((((i&0x8)=0)''((j&0x8))=0))*255; 
image[i][j][0]= (GLubyte) c; 
image[i][j][1]= (GLubyte) c; 
image[i][j][2]= (GLubyte) c; 

1 

glEnable (GL_DEPTH_TEST); /’Enable hidden-surface removal 7 
glClearColord.O, 1.0, 1.0, 1.0); 
glEnable (GL TEXTURE 2D); /* Enable texture mapping V 

glTexTniage2D(GL_TEXTURE_2D.0.3.64,64,0,GL_RGR. 

GL_UNSIGNED_BYTE. image): /* Assign image to texture V 
/* required texture parameters 7 

glTexParameterf(GL_TEXTURE_2D.CL_TEXTURE_WRAP_S. 
GL_CLAMP); 

glTexParameterf(GL_TEXTURE_2D.GL_TEXTURE^WRAP T, 

GL CLAMP); 

glTexPa ramete rf(GL_TEXTIJRE_2D.GL_TEXTURE_MAG_FILTER. 
GL_NEAREST); 

glTexParameterf(GL_TEXTURE_2D.GL_TEXTURE_M1N_E1LTER. 
GL_N£AREST): 


First we create a 64 x 64 image to be used for our 
texture. We enable texture mapping and then pick image as 
the texture map. The other parameters in glTexlmage2D give 
the size of the texture map, specify how it is stored and that 
it will be applied to the red, green and blue components. 
The four calls to gITexparameterf are required to specify how 
values of s and t outside (0,1) arc to be handled (clamped) 
and that we are willing to use the nearest texel (for speed) 
rather than a filtered value. Figure 6 shows the cube with 
both texture mapping and shading. Note that in this mode 
texture mapping modifies the color determined by the 
shading calculation. Alternately, we can have the texture 
cornplclcly determine the color (decaling). 



Figure 6, Texture Mapped Cube. 


Clients and Servers 

In many applications we must convey three-dimensional 
graphical information over a network, either to show the 
graphics remotely or to make use of hardware available on a 
remote machine. Web applications often fall into this 
category. Although we could send two-dimensional images 
across a network, the volume of data can be huge as 
compared to the compact description provided by three- 
dimensional geometry. Furthermore, in distributed interactive 
applications that involve manipulating large graphical 
databases, we would prefer to not have to send the database 
over the network repeatedly in response to small changes, 
such a change in viewing parameters. 

In OpenGL, we regard the hardware with the display 
and the rendering engine as a graphics server and the 
program that defines and controls the graphics as a client. In 
what is called immediate-mode graphics, entities are sent to 
the graphics server as soon as they are defined in a program 
and there is no memory of these entities in the system. We 
used this mode in our sample cube programs. To redisplay 
the cube, we had to reexecute the code defining it. Thus, 
when we rotated the cube, we had to both alter the model- 
view matrix and reexecute the cube code defining its 
surfaces. In retained-mode graphics, graphical entities are 
defined and placed in structures called display lists, which 
are kept in the graphics server. For example, if we want to 
define a quadrilateral, store it on the server, and display it, 
we wrap its description between a gIBeginList and a glEndList: 

Listing 4: Display list for a quadrilateral 

gIBeginList(myQuad. GL_COMPILE_AND_DISPLAY); 
glBegin(GL_QUADS); 
glVertex3fv(a); 
glVertex3fv(b); 
glVertex3fv(c); 
glVertex3fv(d); 
glEndO ; 
glEndList0; 

In this example myQuad is an integer identifier for our 
retained object and the flag GL_COMPILE_AND_DISPLAY 
indicates that we want to define the list and display it on the 
server. If we only want to place a display list on the server 
without rendering it, we use the flag GL_COMPILE. Most 
OpenGL functions can appear inside a display as can other 
code. Similarly, to put a CLi[)e on the server, wc need only 
surround any of our previous cube code with a gIBeginList 
and a glEndList. We might also use display lists to put a 
character set on the server. In general, any objects we intend 
to redisplay are good candidates for display lists. 

Once a display list is on the seiver, we can have it rendered 
by the command such as 

glExecuteList(myCube) 
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Suppose that we wish to rotate the object and then redisplay it 
such as in our rotating cube example from Part 1. Within the 
display callback we would sec code such as 

GlRotaLcf(axis_x, axis_y. axls_z, theta) 

ClExecuteList(myCube); 


In terms of the traffic between the client program and 
the graphics server, we would be sending only the rotation 
matrix and function calls but not the object, as it is already 
stored on the server. If we did the same example using a 
complex object with thousands of vertices, once the object 
was placed on the server, further manipulation would recjuire 
no more network traffic than the manipulation of a single 
quadrilateral or our cube. 

OpenGL plays a vital, but often invisible, role in three- 
dimensional Web applications using VRML (Virtual Reality 
Modeling Language). VRML is based on the Open Inventor 
data base model. Open Inventor is an object-oriented graphics 
.system built on top of OpenGL’s rendering capabilities. VRML 
applications are client-seiYer based with the rendering done 
on the client end. l*hus, a Vl^L browser must be able to 
render databases that contain geometry and attributes that 
looks like OpenGL entities. Consequently, an obvious way to 
build a VRML browser is as an OpenGL application where the 
VRML server places display lists on the graphics server. 

Buffers 

OpenGL provides access to a variety of buffers. These include 

• Color buffers (including the frame buffer). 

• Depth Buffer. 

• Accumulation Buffer. 

• Stencil Buffer. 

Many of these buffers have conventional uses, such as the 
frame buffer and the depth buffer, but all can be read from 
and written into by user programs and thus their uses are 
unlimited. In addition, the OpenGL architecture contains a 
variety of tables associated with these buffers and a variety 
of tests that can be performed on data as it is read from or 
written into buffers. Note that because these buffers are part 
of the graphics system, in an implementation in which these 
buffers and the associated tables are in separate hardware, 
once data have been moved to these buffers, we can achieve 
extremely high data rates as the system processor and bus 
are no longer involved. 

For each type of buffer, we shall consider a few possible 
uses without going into coding details. We have seen that we 
can use multiple color buffers for double buffering. We can 
also use them for stereo viewing by rendering the left and 
right eye views into LEFT and RIGHT buffers and synching 
their display with special glasses that alternate presenting the 
images to the left and right eyes. For stereo animations, we 
can use four color buffers: FRONT_LEFT, FRONT_RIGHT, 
BACK_LEFT and BACK_RIGHT. More generally, we can use 
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color buffers that are not being displayed to enhance the 
power of the geometric pipeline. For example, shadows are 
projections of objects from the perspective of the light 
source. We can do an off screen rendering with the camera 
at the light source into one of the buffers and then carefully 
composite this image with the standard rendering. Another 
application is to render each object in a different color into 
an off-screen buffer. We can use the location of the mouse to 
point into this buffer and the color read at this location is an 
identifier for the object, a simple way of doing interactive 
object selection or picking. 

The depth buffer is used in conjunction with many of the 
applications of the color buffers. One interesting use is for 
combining translucent and opaque polygons in a single 
scene. In our example of blending in Part 1, we turned off 
hidden-surface removal because all the polygons were 
translucent. If some of the polygons are opaque, unless the 
user program sends the polygons down the pipeline in the 
correct order, no combination of enabling hidden-surface 
removal and blending will produce a reasonable image. 
Consider what happens if we render opaque polygons first, 
and then make the depth buffer read-only for translucent 
polygons. Translucent polygons behind opaque polygons 
will be hidden, while those in front will be blended. 

Color buffers typically have limited resolution, such as 
one byte per color component. Consequently, doing 
arithmetic calculations with color buffers can be subject to 
loss of color resolution. The accumulation buffer has 
sufficient depth that we can add multiple images into it 
without losing resolution. Obvious uses of such a buffer 
include image compositing and blending. To composite n 
images, we can add them individually into the accumulator 
buffer and then read out the result while scaling each color 
value by 1/n. If we had tried to add these images into the 
frame buffer, we would have risked overflowing the color 
values, which are typically are stored 8 bits/component. If 
we tried to scale the colors before we added them into the 
frame buffer, we would have lost most, if not all, of our color 
resolution. For example, if n=8, we could loose three bits per 
color component. With an accumulator buffer, we can trade 
resolution for an increase in compositing time. 

Less obvious, but easy to implement, applications of the 
accumulation buffer include digital filtering of images, scene 
antialiasing, depth of field images, and motion blur. Consider, 
for example, ihe antialiasing problem for polygons. As 
polygons are rasterized, the rasterizer computes small elements 
called fragments which are at most the size of a pixel. Each 
fragment is assigned a color that can determine the color of the 
corresponding pixel in the frame buffer. Generally, if the 
fragment is small or fragments from multiple polygons lie on 
the same pixel we will see jagged images if we make binary 
decisions as to whether or not a given fragment completely 


determines the color of a pixel. One solution is to use the 
alpha channel we discussed to Part 1 to allow small amounts 
of color from multiple fragments to blend together. 
Unfortunately, this method can be very slow. An alternative is 
to render the scene multiple times into the accumulation buffer, 
each time with the viewer shifted very slightly. Each image will 
contain slightly different aliasing artifacts that will be averaged 
out by the accumulation process. 

The stencil buffer allows us to draw pixels based on the 
corresponding values in the stencil buffer. Thus, we can 
create masks in the stencil buffer that we can use to do 
things such as creating windows into scenes or for placing 
multiple images in different parts of the frame buffer. What 
makes this buffer more interesting is that we can change its 
values as we render. This capability allows us to write 
programs that can determine if an object is in shadow or 
color objects differently if they are sliced by a plane. 

Performance Tuning 

OpenGL supports a well-defined architecture and as 
such can be implemented in hardware, software or a 
combination of the two. Because there are both geometric 
and discrete pipelines, not only are there a wide range of 
implementation strategies, where bottlenecks arise depends 
on both the application and how the programmer chooses to 
use the OpenGL architecture. Consequently, it is difficult to 
make “one size fits all” solutions to performance issues. We 
can survey a few po.ssibilities. 

Defining geometric objects with polygons is simple but 
can lead to many function calls. For example, our cube with 
vertex colors, normals and texture coordinates required 108 
OpenGL function calls: six faces each requiring a glBegin and 
glEnd, four vertices per face, each requiring a gIVertex, 
glColor, glNormal and glTexCoord. One way to avoid this 
problem if the object is to be drawn multiple times is to use 
display lists. Another is to use vertex arrays, a feature added 
in OpenGL 1.1. In myinit, we can now set up and enable 
arrays that contain all the required information (colors, 
normals, vertices, texture coordinates). A single OpenGL call 

glDrawEleinents(GL_QUADS. 24. GL_UNSTGNED_BYTE. cubeindices); 

will render the six (juadrilateral faces) whose indices are stored 
as unsigned bytes in the array cubeindices, which contains the 
24 vertices in the order they appear in our cube function above. 

In the geometric pipeline lighting calculations can be 
very expensive, especially if there are multiple sources, as 
we have to do an independent calculation for each source. A 
large part of the computation is that of the vectors in the 
Phong model. If a polygon is small relative to the distance to 
a viewer, the view vector will not change significantly over 
the face of the polygon. If we use 
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GlLightModeli(LIGHT_MODEL_LOCAL_VIEWER. GL_FALSE); 

we allow the implementation to take advantage of this 
situation. We can also tell OpenGL whether we wish light 
calculations to be done on only one side of surface through 

GlLightModeli(LIGHT_MODEL_TWO_SIDE, GL_FALSE); 

We can also automatically eliminate (or cult) all polygons 
which are not facing the viewer by enabling culling 

(ClCullFace (GL_BACK)). 

Texture calculations can also be very time consuming and 
are subject to aliasing problems. OpenGL allows us to decide 
if we want to filter a texture to get a smoother image or just 
use the closest texel which is faster. Perspective projections 
can be a problem for texture mapping as the interpolation is 
more complex. In many situations, either the error is small 
enough that we do not care about it or the image is changing 
so rapidly that we cannot notice the error. In these situations, 
we can tell OpenGL not to correct for perspective. 

More generally, we have to worry about both polygons 
and pixels, which are passing through two very different 
pipelines. Depending on both the implementation and the 
application, either pipeline can be the bottleneck. Often 
performance tuning, involves deciding which algorithm best 
matches the hardware and making creative use of the many 
features available in OpenGL. With OpenGL supported 
directly in the hardware of many new graphics cards, many 
graphics applications programmers are rethinking how to 
create images. For example, with the large amounts of 
texture memoiy included on these cards, in many situations 
we can generate details through textures rather than through 
geometry. Often, we can also avoid lighting calculations by 
storing some carefully chosen textures. 

Conclusion 

With over 200 functions in the API, we have only 
scratched the surface of what we can do with OpenGL. The 
major omission in these two articles is how we can define 
various types of curves and surfaces. Nevertheless, you 
should have a fair idea of the range of functionality supported 
by the OpenGL architecture. In the future, the CAD and 
animation communities will not only use OpenGL as their 
standard API but also start making use of features particular 
to OpenGL, such as the accumulation and stencil buffers. 

The advantages of OpenGL are many. It is close to the 
hardware but still easy to use to write application programs. 
It is portable and supports a wide variety of features. It is the 
only graphics API that I have seen in my 15 years in the field 
that is used by animators, game developers, CAD engineers 
and researchers on supercomputers. Personally, I routinely 
use OpenGL on a PowerMac 6100, a PowerBook, an SGI 


Infinite Reality Engine and a variety of PCs, rarely having to 
change my code moving among these systems. There is not 
much more that can I ask of an API. 

Sources and URLs 

OpenGL is administered through an Architectural Review 
Board. The two major sources for on-line information on 
OpenGL are the OpenGL organization <http://www.opengl.org> 
and Silicon Graphics Inc <http://www.sgi.com/Technology/OpenGL>. 
You can find pointers to code, FAQ, standards documents and 
literature at these sites. I keep the sample code from my book 
at <ftp://ftp.cs.unm.edu under pub/angel/B00K>. 

OpenGL is available for most systems. For Mac users, 
there is an implementation from Conix Enterprises 
<http://www.conix3d.com> that includes support for GLUT and 
for hardware accelerators. There is a free OpenGL-like APT 
called Mesa <http://www.ssec.wisc.edu/~brianp/Mesa.html> that 
can be compiled for most systems, including linux, and will 
run almost all OpenGL applications. There is a linux version 
available from Metro Link <http://www.metrolink.com>. You can 
obtain the eode for GLUT and many examples at 
<http://reality.sgi.com/opengl/glut3/glut3.html>. 
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GAMES 

PROGRAMMIlUG 


by Brent Scborsch 


Inside InputSprocket 


How to Use InputSprocket 
to Support User Input 
in Games 


Introdiktion 

Handing user input is a necessary 
aspect of a game. Without user input, it 
is not a game, but just a flashy movie. 
This article will cover what a game 
developer needs to do in order to handle 
user input using InputSprocket, Apple’s 
gaming input API. InputSprocket was 
created to address the lack of a common 
API for joysticks and other gaming 
devices on the Macintosh platform. With 
the introduction of the iMac and USB, 
InputSprocket has opened the door for 
numerous gaming hardware 
manufactures to sell their products to 
Macintosh customers. Game developers 
also benefit by supporting InputSprocket 
because their game will support the 
latest input gadgets with no extra effort 
from the game developer. Game players 
benefit from the increased options. 

The Basics 

InputSprocket is a relatively simple 
API to use. There are some more 
complicated aspects, which will be 
covered later, but the basics are 
straightforward. First, an application 
must p^rovide a list of its input needs to 
InputSprocket. Example needs a game 


might have are: fire weap)on, jump, turn, look, rudder, lower 
landing gear. The list of needs determines how the user can 
interact with the game and therefore will directly affect 
whether the game is thought to be hard to control or very 
intuitive and flexible. 

Once InputSprocket is initialized and has the list of 
needs, there is a single APT call (ISpConfigure) which will 
bring up a user interface, provided by InputSprocket, for the 
user to map the physical elements of the device to needs in 
the game. InputSprocket maintains the user's settings in a 
preference file. This dialog is pictured in Figure 1. 

During game play, the application can either get events 
or poll the current value for any of these needs. Typically, 
applications will get events on ‘button kind’ needs (and 
others) and poll the value of ‘axis kind’ needs once per game 
loop. The different ‘kinds’ of needs is covered later. 



Figure 1. InputSprocket Configure Dialog. 
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The ‘Low Level’ Interi ace 

In fact, there are two different ways an application can 
use InputSprockel: ‘low-level’ and ‘high-level’. The ‘low- 
level’ interface provides a means for the developer to get a 
list of the devices currently available and manually check the 
state of each device. This interface is strongly discouraged. It 
is provided for those developers who wish to provide their 
own user interface to configuring device, but it puts a much 
greater burden on the game developer. With this interface, 
the game developer is responsible for determining how each 
kind of device might be configured to work with their game 
and to provide a complete user interface to make this 
configuration. Gaines that use the ‘low-level’ interface lose 
any extra functionality that is provided by the high level 
interface. The rest of this article will focus on the ‘high-level’ 
interface, which is the one that all game developers are 
encouraged to use. 

Determining the Game’s Needs 

There are four basic need kinds: button, direction pad 
(dpad), axis and delta. (There is also a movement kind, but 
its use is discouraged.) Each kind has a different data format, 
fhe button kind is the simplest, with values of up or down. 
A dpad has nine possible values: idle, left, up-left, up, up¬ 
right, right, down-right, down, and down-left. An axis kind’s 
value is a 32 bit unsigned number, regardless of whether it is 
symmetric. Finally, the value of a delta type is a 32 bit Fixed 
point number of inches moved. 

When deciding what kind to make a particular need, one 
should prefer the axis kind to button and dpad kinds when 
applicable. This will allow game players to get the full 
functionality out of their equipment. Sure, keyboard users 
may only be able to either walk or run (forwards or 
backwards), but if someone has a device with enough 
‘analog’ inputs, the game should let him continuously vary 
his speed. In some cases, it may be necessary to provide 
some extra information to InputSprocket so that the 
keyboard user experience is maintained which is covered 
later. Delta kinds are provide data similar to ‘raw mouse’ data 
but due to limitations in the current InputSprocket drivers, 
are most useful in the more complex InputSprocket cases, 
where once again extra information is provided. 

In some cases, it may make sense to provide several 
needs that affect the same thing in the game world. For 
example, in addition to a ‘next weapon’ and ‘previous 
weapon’ need, it often makes sense to provide needs to 
switch to specific weapons, e.g. ‘use machine gun’, ‘use 
plasma rifle’. The code necessary to support these different 
means to switch weapons is trivial, but the added 
functionality to certain users (with the right hardware) is 
immense. The speech recognition InputSprocket driver does 
not add much if you can only say ‘next weapon’, but if you 
can say ‘use plasma rifle’, then it might start to be appealing. 
Another case where multiple needs might make sense is 
where the need is some form of toggle, such as ‘map mode’ 


or ‘landing gear’. One button may be sufficient for most users, 
but if the hardware physically has two states, like the caps 
lock key on some keyboards or any sort of lever, then it is 
very easy for the physical device to become out of .sync with 
the game. However, by adding two more needs, switch to 
map view (or landing gear up) and switch to non-map view 
(or landing gear down), it is impossible, when properly 
configured, for the hardware to be out of sync with the game, 
regardless of the starting state of the game and the hardware. 

Finally, it often makes sense to use the native data types 
as input for the game. This is a case where the game 
essentially gives InputSprocket extra information so that it 
can behave better. It does this by providing multiple needs, 
of different data kinds, to change the same thing in the game 
state. An example where this is useful is for the traditional 
rudder controls on a flight-sim. Typically, the keyboard 
commands to change ihe rudder are ‘Increase Left Rudder’, 
‘Center Rudder’, and ‘Increase Right Rudder’. Each time 
either of the ‘Increase ...’ keys are pressed, the current 
rudder value is changed. In order to restore the plane back 
to no rudder, you have to either manually press the keys 
enough times to get back to center, or press the ‘Center 
Rudder’ key. The current ‘InputSprocket Keyboard’ driver 
does not allow the user to configure an axis need to three 
keys like this, so this case calls for using extra needs. In 
addition to the rudder axis need (for those who have a 
device such as a rudder or twisting joystick), the game will 
have three button needs: left rudder, center rudder, and right 
rudder. The axis need should set the 

klSpNeedFlag_Axis_AlreadyButton bit in the ISpNeed, flags 
field and the button needs should set the 
klSpNeedFlag_Button_AlreadyAxis bit. Another common case 
for using button and axis types is for a throttle in a flight-sim. 

Listing 1 contains the complete list of needs chosen for 
the sample application. Listing 2 is an excerpt from the 
sample application which demonstrates using axis and 
button types to change yaw angle. The 

klSpNeedFlag_Button_AlreadyDelta bit is also set, because 
the sample application also reads delta types separately. 
Typically, delta types are used when the developer wants the 
‘feel’ of using a mouse to be similar to how it typically feels 
in a first person shooter, like Unreal or Quake. 

Listing 1; ISp_Sample.h 

Thi.s is an cxccrpi from ISp_Sample.h containinj; the enumeration of all the needs. 

enum 

( 

// primary needs 

kNeed_FireWeapon, 
kNeed_NextWeapon. 
kNeed PreviousWeapon, 

kNccd_Roll, 

kNet!d_Pitch. 

kNeed_Yaw, 

kNeed_Throttle. 
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kNGed_StartPause. 
kNeed_Quit. 

// secondary needs for alternative input kinds 

kNeed_Weapon MachineGun, 
kNeed Weapon_Cannon, 
kNeed Weapon_Laser, 
kNGed_Weapon_Missle, 
kNeed_Wcapoii_FrecisionBomb, 
kNce<I_Weapon_ClusterBomb, 

kNeed_Roll_AsDelta, 
kNeed_Pitch AsDelta, 
kNeed_Yaw AsDelta, 

kNeed_Yaw_LGft, 
kNecd_Yaw_Center, 
kNeed_Yaw_Right, 

kNeed_Throttle Min, 
kNeed_Throttle Decrease, 
kNeed ThrottTe_IncrGasG, 
kNGGd_Th ro 11lG_Max, 

kNeGd_NeedCount 

); 


Listing 2; ISp_Sample.c 


Input_Initialize 

'iTiis is an excerpt from InpuMnitializc which initializes the needs array. 

//• we’ll init all the player 1 items now 

//• (everything but quit unless we add a second player) 

tempNeed.playerNum “ 1; 

// [snip - code removed from this listing] 

// Now gn)up 4, which is for changing yaw 
tempNeed.group " 4; 

GetTndStriiig (tempNeed.name, kSTRn NeedNaraes, 
kNeed_Yaw + 1); 

tempNeed.iconSuiteResourceld = 1000 + kNeed_Yaw; 
tempNeed.theKind = kISpKlemGntKind_Axis: 
tempNeed.theLabel “ kISpElementLabel_Axis_Yaw; 
tempNeed.flags * klSpNeedFlag_Axis_AlrGadyButton: 
myNeeds[kNeGd_Yaw] = tempNeed; 

GelIndString (tempNeed.name, kSTRn_NecdNames, 
kNeed Yaw^Left + 1): 

tempNeed.iconSuiteRe.sourceld = 1000 + kNeed_Yaw Left; 
tempNeed.theKind “ kTSpElemGntKind_Button; 
tempNeed.thel,abcl = klSpElementLabel_NonG; 
tempNeed.flags = klSpNeedFlag_Button_AlreadyAxis | 

klSpNeedFlag Button_AlreadyDelta j 
klSpNeedFlag Event.sOnly; 
myNeeds(kNeed_Yaw_Left] = tempNeed; 

CetIndString (tempNeed.name, kSTRn_NeedNames, 
kNccd_Yaw_Center + 1); 

tempNeed.iconSuiteResourceld = 1000 + kNeed_Yaw_CGnter; 
tempNeed.theKind = kISpElementKind Button; 
tempNeed.theLabel = kISpElementLabe]_NonG; 
tempNeed.flags “ kISpNeedFlag_Button_AlreadyAxis | 

kISpNeedFlag_Button_AlreadyDelta | 
kTSpNecdFlag_EventsOnly; 
myNeedsfkNeed_Yaw_Center] = tempNeed; 

GetTndSlring (tempNeed.name, kSTRn NeedNames, 
kNeed_Yaw_Right + 1); 

tempNeed.iconSuiteResourceld = 1000 + kNeed_Yaw_Right; 
tempNeed.theKind = kISpElementKind_Button; 
tempNeed.theLabel = kTSpElGmentLabel_None; 
tempNeed.flags » kTSpNeGdFlag_Button_AlreadyAxis | 

klSpNeedFlag_Button AlreadyDclla | 
kISpNeedFlag_EventsOnly; 
myNeeds[kNGed_Yaw_Right] “ tempNeed; 


Listing 2 also demonstrates the other fields that must be 
filled in the ISpNeed structure. The name field contains a 


string to be displayed to the user in the configuration dialog 
(shown in Figure 1), typically in the popup menus for each 
device element (altliough the su-ings appear directly for 
keyboard devices). The IconSuiteResourceld field contains the 
resource ID for an icon family that represents that need, 
lypically ‘ics#’ and ‘ics8’ icons are provided, since all the 
current drivers only display 16x16 icons. The theKind field 
determines whether the need is a button, delta, axis, dpad, 
or something else. The theLabel field is used to give hints to 
TnputSprocket about how the need is used. There will 
inevitably be needs in every game that arc not described by 
one of the labels in InputSprocket.h, those needs should use 
the kISpElementLabeLNone label. Another bit set in the flags 
field in this listing is kISpNecdFlag_EventsOnly which tells 
InputSprockel that it does not have to maintain state 
information for this need. The group was set at the top of the 
listing, so that it is the same for all these needs. By 
convention, all the needs which affect the same game state 
are set to the same group. 1’he full source for Inputjnitialize 
in lSp_Sample.c uses five groups: changing weapon, roll, 
pitch, yaw, throttle. 

INIXIALIZATION 

There are several InputSprockel functions which will 
typically be necessary during initialization. First, 
ISpGetVersion should be used to confirm that InputSprocket 
is available and of a minimum version for the game. Next, 
ISpStartup should be called to gel InputSprocket up and 
running. ISpElement_NewVirtualFromNeeds is used to create 
and allocate virtual elements for each need. Virtual elements 
are the objects that arc used to get events or are polled. Now 
ISpInit can be called to initialize the ‘high-level’ interface to 
InputSprocket. ISpInIt provides InputSprockel with the needs 
list and the previously allocated virtual elements. It is often 
convenient to get events on an element list, which is just a 
grouping of (in this case virtual) elements. 
ISpElementList_New is used to allocate a new elements list 
and ISpElementLisLAddElements is used to add one or more 
elements. Typically, one element list is u.sed for all the 
regular button needs and an additional element list is created 
for each group of buttons which correspond to an axis need. 
Listing 3 is an excerpt from lnput_lnitlalize which 
demonstrates all of these functions. 

Listing 3: ISp_Sample.c 


Inpul_Initiali 2 c 

Tliis is an cxccrpt from Input_InitiaJizc whicli initializes InputSprocket with the needs 
list and builds an element list. 

//* Alright, now that the array is set up, we can call ISp to init stuff 
err = ISpStartup (); 
if (err) 

ErrorAlert(“\pCould not Initialize InputSprockel.”, err, true); 

//• Setup the input sprocket elements 

err = ISpEleinenl_NGwVirtualFromNeeds(kNeed NeedCount. 
myNeeds, gInputElements, 0); 

if (err) 

ErrorAlert ("\pCould not create ISp virtual controls from needs.”. 
err, true); 
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//• Init InputSprocket and tcU it our needs 

err = ISpInit (kNeed.NeedCount. myNeeds, gInputElements, 
klSpSamplcCreator. kISpSampieNeedsVersion. 

0, ksetl_lSpSample. 0): 

if (err) 

ErrorAlert (“\pCouId not initialize high-level ISp”, err, true); 

//• Create a element list conlaing all Uic normal’ buttons (we get events on these) 
err = ISpElementList New(0. NULL. &gEventsElementList. 0); 
if (err) 

ErrorAlert (**\pCould not create button element list.”. err. true); 


//• we set the refcon to the need enum value, so we can use it later 
//• doing .some shortcut error checking for readability 
err " TSpElementList_AddEiemeiits {gEventsElementList, 
kNeed FireWeapon, 1. 

&gInputElements fkNeed_FireWeapon]); 
iSpElefiicnLL.lst._AddElements (gEventsElementList, 
kNeed_StartPause. 1. 

&gInputElements[kNeed_StartPause]); 

ISpElementList_AddElenienLs (gEventsElementList. 
kNeed NextWeapon. 1. 

6rgTnputElements[kNeed_NextWeapon]); 
ISpElementList AddElements (gEventsElementList, 
kNeed_PrcvlousWeapon, 1, 
fitglnputElemenls[kNeed PreviousWeapon]); 


err 

err 

err 

err 

err 

err 


ISpElementList.AddElcmenis (gEventsElementList, 
kNeed_Weapon_MachineGun, 1, 

&gInputElementslkNeed_Weapon_MachineGunl); 

ISpElementList AddElements (gEventsElementList, 
kNeed_Wea pon_Cannon, 1, 

&glnputElemcnts(kNeed Weapon_Cannon]); 

ISpElementList_AddElcments (gEventsElementList. 
kNeed_Weapon_Laser, 1, 

&gInputElements[kNeed_Wcapon_Laserl); 

TSpElementList_AddEleraents (gEventsElementList, 
kNeed_Weapon Missle, 1, 

&gInputElements[kNeed_Weapon_Missle]); 

ISpEleraentLisL_AddEleraents (gEventsElementList, 
kNeed_Weapori_Precis i onBomb, 1, 

&gInputElemeiits[kNeed_Weapon_PrecisionBombJ); 

ISpElementList_AddElemcnts (gEventsElementList, 
kNeed Weapon_CiusterBomb,1, 

&gTnputElements[kNeed_Weapon_ClusterBomb]); 


err 


ISpElementList_AddElements (gEventsElementList, 
kNeed_Quit, 1, 

SglnputElements[kNeed_Quitl); 


if (err) 

ErrorAlert( 

“\pCould noi fill button element list Error number may be inaccurate.", 
err, true); 


Cooperating with Mac OS 

By default, InputSprocket assumes that a game has its 
own method, using traditional Mac OS technicjucs, to get 
user input from all mice and keyboards. If a game wants to 
use InputSprocket for keyboard and/or mouse input, it must 
enable those classes of device with 
ISpDevices_ActivateClass. Activating the mouse class will 
disconnect all mice and trackballs from controlling the 
cursor, so should only be done while the game is in progress 
and only if the Mac OS cursor is not necessary to play the 
game. Activating the keyboard class will prevent the 
keyboard from generating any Mac OS events, although 
GetKeys will still function. 

The game developer must decide whether to use 
InputSprocket for mouse and/or keyboard input. Using 
InputSprocket for mouse input is recommended for games 
that do not use the Mac OS cursor during play. The primary 


advantages in this case are that multi-button mice are easily 
supported and configured, and that the user interface is 
consistent with other gaming devices. For those game 
developers who do not already have a method they prefer to 
get keyboard data, using InputSprocket for this purpose will 
save time. However, InputSprocket is not an appropriate way 
to get ‘typing’ input from the user (such as a message that the 
user is sending to other players), so the keyboard class 
should be deactivated and traditional Mac OS means used 
whenever ‘typing’ is initiated. 

Because InputSprocket assumes control of all the active 
devices when it is active, it is necessary to suspend it when 
the application is placed in the background. When the 
application is placed in the foreground again, InputSprocket 
may be resumed. It is very important that InputSprocket not 
be left active when the application is not front-most. These 
operations are normally performed on the response of a 
suspend/resume OS event and are performed by the functions 
ISpSuspend and ISpResume. It is safe to use these functions at 
other times while the application is front-most if desired. 
However, a slightly better experience may be possible if just 
the keyboard and mouse classes are disabled. This way, for 
example, the ‘start’ button on a gamepad can still be used to 
start a game. The sample application lakes the latter approach. 
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Getting User Events 

The sample apf)licali()n sets up a element list for all the 
normal button elements with the refcon value the same as the 
enum value for that need. ITiis makes taking action based on 
the event almost trivial, as Listing 4 demonstrates. 
ISpElementList_GetNextEvent is used to get the next event on the 
queue for the element list. ISpTIckle is a way to give time to 
InputSprocket drivers even if the game does not call 
WaitNextEvent. It must be called at task level (not interrupt 
level), but is only required for drivers which must be manually 
enabled (like s{)eech recognition). It is recommended that all 
games give time, but it is not necessary. It is also reasonable for 
a game to limit calls to ISpTIckle to a few per second. 

Listing 4: ISp^Sample.c 


Input, GetButtonFvents 

ITiis function i.s u.sed to modify the gameStale structure if any of the primary buttons 
have been pres.sed.This function is called as part of the normal game loop. 

void Input_CetButtonEvents (Input GameState * gameState) 

OSStatus error = noErr; 

ISpEiementEvent event: 

Boolean wasRvent; 

// give time to some non-inierrupl driven input drivers (like speech recognition) 
TSpTickle 0; 

// get ail pending events 

do 

f 

error = TSpElementList_CetNextEvent (gEvent.qElemciUList, 
sizeof (event), fitevent, &wasEvent): 

if (wasEvent && terror) 

I 

switch (event.refCon) 

1 

ca.se kNced^FireWeapon: 

if (event.data ^ kISpButtonDown) 

f 

gameState->fireWeaponState = true: 
gameState->fireWeaponCount++: 

else // (cvcnt.data = kiSpButtonUp) 

gameState >fireWeaponState = false; 
break: 

case kWeed_StartPause: 

if (event.data = kISpButtonDown) 

I 

if (!gameState >gameInFrogress) 
gameState >gamelnProgress “ true; 
el sc 

gameState->gamePaused = 

! gameState - >gamePaiJsed; 

1 

break: 

case kNeed NextWcapoii: 

if (event.data = kISpButtonDown) 

I 

gameState->currentWeapon++: 
if (gameState->currentWeapon >= 
kWeapon WeaponCount) 
gameState->currentWeapon = 0: 

break: 

case kNeed_PreviousWeapon: 

if (event.data = kISpButtonDown) 

I 

gameState - >cij r ren t Weapon-; 


if (gameState >currentWeapon < 0) 
gameState >currentWeapon = 
kWeapon_WeaponCount - 1; 

) 

break; 

case kNeed_Weapon MachineGun: 

if (event.data ” kISpButtonDown) 

gameState->currcntWeapori = kWeapon_MachineGun: 
break; 

case kNeed_Weapon_Cannon: 

if (event.data — kISpButtonDown) 

gameState->currentWeapon - kWcapori_Cannon; 
break; 

case kNeed Weapon_Lascr: 

if (event.daLa — kISpButtonDown) 

gameState->currentWeapon - kWeapon Laser; 
break; 

case kNeed_Weapon_Missle: 

if (event.data = kISpButtonDown) 

gameState->cijrrentWcapon = kWeapon_Missle: 
break; 

case kNcGd_Weapon_PrecisionBomb: 
if (event.data “ kISpButtonDown) 
gameState->currentWeapon ■ 
kWeapon_PrecisionBomb; 
break: 

case kNeed_Weapon_ClusterBomb: 
if (event.data = kISpButtonDown) 

gameState->currentWeapon = kWeapon_ClusLerBomb; 
break; 

case kNeed_Quit: 

gamGState->gameTnProgrcss = false; 
break; 

1 

) 

) 

while (wasEvent && !error); 

1 


POLLINIi Axis VAI.IIF.S 

The .sample application reads axis values for roll, pitch, yaw, 
and throttle. The most complicated one is yaw, wliich is shown in 
Listing 5. When there are lx)ih an axis and button needs that map 
U) the .same game state, there is an easy technique to get the 
correct Ix-havior. First, ISpElement_GetNextEvent is used on the 
axis element just to check to see if the axis value changed. If it 
did change, then ISpElement GetSimpleState is used to poll the 
current value of that axis element. Both the axis element and the 
element list are then flushed. However, if the axis value has not 
changed (wasEvent is false), then ISpElementList_GetNextEvent is 
used to get all the button events on the element list containing the 
buttons for die axis. Delta values are actually handled differently 
at a higher level, so they are read and accumulated into a separate 
value in the state staicture. 

Listing 5: ISp_Sample.c 


Input_GetYaw 

This hinction Ls u.sed to modify the gameState structure to include the latest changes 
in yaw based on user input.This function is catted as part of the normal game loop. 

void Iriput_GetYaw (Input_GameStatG * gameState) 

OSStatus error “ noErr; 

ISpEiementEvent event; 

Boolean wasEvent; 

TSpAxisOata axisValue; 

SInL32 yawValue * gameState->yawInpuL; 
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) 


// wc check llic axis, to see was moved, if so, we use that value 
error “ ISpElemGnl_Ger.NextEvent (glnputElcments [kNeed_Yaw]. 

sizeof (event), &event. &wasEvent); 
if (!error && wasEvent) 
f 

// wc wish to ignore all button presses _prior_ to this moincni 
ISpElementList. Flush(gYawElementList); 

// gel the current value 

error “ ISpElemGnL_GetSimpleState 

(glnpiitElements [kNeed_Yaw] , &axisValue): 

if (lerror) 
yawValiie = 

ISpAxlsToSampleAxis (axisValue. kMin_Yaw. kMax_Yaw); 
ISpEieinenl_Flush{gInputEleinents [kNccd_Yawl); 

) 

// otherwise, we check to see if one of the yaw buttons was pressed 
else do 
( 

error TSpElementList_GetNcxtEvent (gYawElementList. 

sizeof (event), ^levent, &wasEvent); 

// only process valid keydown events (all the yaw events ignore button ups) 
if (wasEvent && lerror && (event.data ^ kT.SpButtonDown)) 
I 

.switch (event. refCon) 

( 

case kNeed_Yaw_Left: 

yawValue klncreraent.Yaw; 

if (yawValue < kMin_Yaw) yawValue = kMin_Yaw: 

break; 

case kNeed_Yaw_Center: 

yawValue = kMln_Yaw ^ ((kMax_Yaw kMin_Yaw) / 2); 
break; 

case kNeed_Yaw_Right: 

yawValue kIncremcnt_Yaw; 

if (yawValue > kMax_Yaw) yawValue * kMax_Yaw; 

break; 


1 

I 

while (wasEvent && lerror); 

gamoState->yawInput = yawValue; 

//• also check the delta values 
gameState >deltaYaw “ 0; 
do 
( 

error ** ISpElenient_GctNextEvGnt 

(gInputElemcnts[kNeed Yaw_AsDelta], 
sizeof (event), &event, &wasEvent); 
if (wa.sEvent && lerror) 

gameState->deltaYaw += (Fixed) event.data: 

I 

while (wasEvent && lerror); 


InputSprocket Resources 

InputSprocket checks for certain resources inside an 
application. First, the aj^filication should have an InputSprocket 
application resource (‘isap’) which simply specifies how the 
application uses InputSprocket. Next, the application should have 
a set list resource (‘.setl’). It is ok if there are no sets contained in 
this resource, but it should be pre.sent. The set list resource 
contains pointers to individiml saved-set resources (‘tset’). Saved 
set resources contain a set of configuration infonnation for a 
single device for a specific application. InpuLSf)rocket.r contains a 
resource template for a saved-set resource that corresponds to a 
keylxiard device. 'Fhis template can be used to put keyboard 
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defaults in a ‘.r’ file. The saved set resources for all the other 
devices do not have templates. This means that the developer 
must execute the built game, manually create each set he wants 
to include with the game, and then copy these sets from the active 
‘Input Sprocket Preferences’ file (in the Preferences folder) to his 
‘.r’ file. The sample application includes two sets for tlie keyboard 
and two for the mouse. Fortunately tlie default settings for most 
drivers (other than tlie keyboard) are pretty g(K)d if the developer 
is careful about ordering his needs list, so it is usually not 
necessary to provide sets besides those for the keyboard. Listing 
6 contains the resource descTiption for tlie default keyboard set in 
the sample application. If the keyboard saved set resource does 
not have the correct number of items, then it will not function 
even though it may still be displayed in tlie sets menu. ITie easiest 
way to debug this is to compare a saved set resourc:e generated 
by a ‘.r’ file with one created by the ‘InputSprocket Keyboard’ 
driver in tlie ‘InputSprocket Preferences’ file. Also note tliat tlie 
default sets are only copied once from tlie application to the 
‘InputSprocket Preferences’ file, so it usually will lx: necessary to 
delete die ‘InputSprocket Preferences’ file from the preferences 
folder several times during development. 

Listing 5: ISp.Sample.r 

k.tset_Defaul t Keyboard 
This is the resource description for the default keyboard set in the sample application. 

#define rNoModifiers rControlOff, rOptionOff, rShiftOff, \ 
controlOff, optionOff. shiftOff, commandOff 

resource ’tset' (ktset_DefaultKeyboard, “Default (Keyboard)”) 

{ 

supportedVersion, 

( 

/* kNecd_FireWeapon 7 
kpdOKey, rNoModifiers, 

r kNeed_NcxlWeapon V 
kpd9Key. rNoModifiers, 

/• kNccd_PrevioasWeapon V 
kpd7Key, rNoModifiers, 

r kNeed_RoU V 
/* min (Icft/down/back) */ 
kpd4KGy, rNoModifiers, 


r kNccd_Wcapon_Cannon V 
n2Key, rNoModifiers, 
r kNced_Weapon_Lascr V 
n.3Key, rNoModifiers, 
r kNeed_Weapon_Misslc V 
n4Key, rNoModifiers, 
r kNccd_Wcapon_PrccksionRomb 7 
n5Key, rNoModifiers, 
r kNecd_Wcapon_ClusterBomb 7 
n6Key, rNoModifiers, 

r kNeed_Roll_AsDcUa 7 

r this need does not generate any items - the keyboard does not do deltas 7 
r kNccd_Pilch_AsDelta 7 

r tliis need does not generate any items - the keyboard does not do deltas 7 
r kNeed_Yaw_A.sDclta 7 

r this need docs not generate any items - the keyboard does not do deltas 7 

r kNeed_Yaw_Lcft 7 
aKey, rNoModifiers, 
r kNccd_Yaw_Cenier 7 
sKey, rNoModifiers, 

/• kNeed_Yaw_Right 7 
dKey, rNoModifiers, 

r kNced_Throttle_Min 7 
kpdKqualKey, rNoModifiers, 
r kNecd_Throllle_Decre'ase 7 
kpdMinusKey, rNoModifiers, 
r kNced_'rhroillc„lncrease 7 
kpdPlusKey, rNoModifiers, 
r kNccd_Throttle_Max 7 
kpdSlashKey, rNoModifiers, 

); 

); 


Final Word 

Using InpuLSpnx'ket for user input in games is a good idea. It 
is relatively simple to implement, and both tlie developer and 
game player benefit. With the inlrcxluction of the iMac, and its USB 
ports, tlie number of input devices available to Macintosh 
cTistomers is balkxining. At the lime tliis was written, the current 
version of InputSprcx:kei was 1.4. The latest version and 
infonnaiion is available at <http://developer.apple.com/games/sprockets>. 
Examining the sample application, which was written using the 
techniques in this article, should be the next step for a developer 
interested in using InpuLSpmcket. The finished application is 
pictured in Figure 2. 


/* max (righl/up/forward) ♦/ 
kpdbKey, rNoModifiers, 

r kNeed_Pitch 7 
r min (left/down/back) 7 
kpdSKey, rNoModifiers, 

/♦ max (righl/up/forward) ♦/ 
kpdSKey, rNoModifiers, 

r kNeed.Yaw 7 

r this need docs not generate any items, because it has later button equivalents 7 
r kNeed_Throttlc 7 

/* this need does not generate any items, because it has later button equivalents 7 

r kNecd_StartPause 7 
tildeKey, rNoModifiers, 

r kNeed_Quit 7 

qKey, rControlOff, rOptionOff, rShiftOff, 
controlOff, optionOff, shiftOff, coramandOn, 

r kNeed_Wcap<)n_MachineGun 7 
nlKey, rNoModifiers, 



Figure 2. ISp^Sample in action. 
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Edited by Michael Brian Bentley 


External Function Plug-ins for FileMaker Pro 


An Introduction to Their 
Nature and Creation. 


FileMaker Pro and Plug-ins 

FileMaker® Pro software is the 
database of choice for Mac OvS users; part 
of its success has been due to the very 
accessible user interface. Much of what 
you do is point-and-click. Up until 
recently, the closest to programming you 
could get is a very complex calculation 
formula or script. Plug-ins introduce a level 
of programmability never before available. 

A script in FileMaker Pro is not 
unlike a macro in a word processing 
application. Scripts are great for 
automating tasks you can do manually in 
the user interface such as switching 
layouts or printing a report, but they 
must be initiated by the user. 
Calculations are performed without user 
input and are adequate for typical usage, 
since calculations are written in a high 
level syntax that is interpreted by the 
FileMaker Pro calculation engine. 
Creating a formula merely requires that 
you assemble a series of built-in 
functions from various categories. 

A calculation formula like “fieldA + 
SinCfieldB)” can be created entirely by 
the point-and-click interface. 

The problem is, formulas that 
require recursion or looping arc not 
possible in calculations. Typical kinds of 
functions are built-in, like trigonometric 
functions, but industry-specific 


algorithms, like annuity functions based on payments at the 
beginning of a period, arc not. 

Scripts support recursion and looping, but require the 
u.ser to execute them. 

Both calculations and scripts interact with other parts of 
a FileMaker Pro database. 'Phe various parts of FileMaker Pro 
integrate well, but a database is closed to the outside world 
of the OS and/or other applications. What if your calculation 
requires some information from another SDK? What if you 
wanted to create your solution to prc.sent to the user a very 
specific style of dialog boxes? 

With AppleScript and the right scripting addition, you 
could achieve some sort of integration with another 
application. With some layout tricks, you could simulate 
dialogs. However, this just isn’t the same as having a 
programmable feature within the application that would give 
you direct access to the OS or another SDK. 

FileMaker Pro “External Function Plug-ins” can bridge 
this gap between the application’s predefined interface and 
your need for a custom one. An APT/SDK was released for 
FileMaker Pro 4.0 that allows you to create your own 
compiled code that can be referenced by a formula in a 
calculation, as an “External” function. When an External 
function is referred to, FileMaker Pro passes program control 
over to the external code you created. Your plug-in can then 
do what it needs to do and pass the needed information (and 
program control) back to FileMaker Pro. 

By using an External Function Plug-in, you can use 
calculation formulas that take advantage of things like 
recursion and looping. Plug-ins can hook into other 
applications or the Mac OS toolbox. This means things 
previously impossible with calculations and scripts are now 
within the database developer’s reach. 

For brevity and focus, this article assumes you have at 
least a rudimentary knowledge of FileMaker Pro calculation 
fields and scripts. 


David McKee is the author of many FileMaker Pro plug-ins, including the “Full Example” plug-in for the FileMaker Pro 
Developer Edition. He presented a .seminar on writing plug-ins at the 1998 FileMaker Developer Conference and works in tlie 
Engineering department of FileMaker, Inc. 
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Terms 

The following are terms used within this artic:le. They are 
included for those new to programming plug-ins or modules. 

• Plug-in 

A plug-in is a file separate or external to the 
application that contains executable code. The 
application loads the plug-in at runtime and passes 
information and control to the plug-in whenever 
needed. The advantages of putting some features in a 
plug-in include easier revision of the feature, as well 
as allowing the application author to open up feature 
creation or modification to the public without 
exposing sensitive parts of the program. 

A plug-in is essentially a separate application that is 
complied as a code resource or library. It inhabits the 
same application space as the host program that 
loaded and passed execution to it. 

• Parameter Block 

A Parameter Block is the sole shared data structure 
that gets passed between the program and the plug-in. 
This allows data and functions to be passed 
seamlessly, even though they are basically two 
separate applications. If a particular function is not 
supported by the parameter block, then the desired 
control or communication between the two entities is 
probably not possible. 

• API 

An API, or Application Programming Interface, is a set 
of standards that your application must adhere to in 
order for it to be usable with the host program or 
standard. Some APIs are header and source code 
documents that you are required to use when 
compiling, your code, while other APIs are just header 
files that allow you to link to a provided library. 

There are no extra libraries needed to create a FileMaker 
Pro plug-in other than the ones you would normally 
need to create a code resource or shared library. 

• SDK 

An SDK, or Software Development Kit, is often used 
interchangeably with API. 

• External function 

An External function is a new class of calculation 
functions that can be used in a calculation formula. 
First introduced in FileMaker Pro 4.0, functions in this 
class are not built into the application. External 
functions can be designed and used in two ways. 


When used from within a calculation field, as part of 
a formula, the External function behaves as a function. 

In this case, the External function returns data that will 
be used as part of the formula. 

When used from a SetField script step, where an 
action is involved, the External function behaves as a 
command. In this case, what the External function 
returns may only be a result/error code. 

• External Function Plug-in 

An External Function Plug-in is a third-party file that 
contains External functions. These are loaded by the 
FileMaker Pro application upon startup. The External 
functions are then listed in the calculation dialog box 
interface of FileMaker Pro. 

• Feature String 

A Feature String is a series of flags that inform 
FileMaker Pro how to utilize the plug-in. Part of the 
Feature String is the “Feature String ID”, which is 
essentially a Mac OS creator code that uniquely 
identifies that plug-in. No two plug-ins should have 
the .same Feature String ID. 

• FileMaker Pro Developer Edition 

The FileMaker Pro Developer Edition (DE) is a 
FileMaker, Inc. product for high-end FileMaker Pro 
developers. This product includes many developer- 
oriented products that are of little use to end users. 
The Developer Edition (DE) is required to obtain the 
External Function Plug-in API. However, plug-ins 
created with the API can be used on any FileMaker Pro 
4.0 (or greater) based product. 

Before Starting 

External Function Plug-ins (EFPs) were primarily intended to 
allow .someone to supplement the list of calculation functions. 
While EFTs can supply many functions, you should consider a 
plug-in a toolbox of similar features. Tiy to focus your plug-in 
project on a certain function or tight group of functions. “Swiss 
army knife” plug-ins with unrelated functions will confu.se end 
users and not distinguish your plug-in from others. 

Non-programmers will use EFPs you create for their 
databases. Most FileMaker Pro database developers may not 
understand programming conventions that you take for 
granted. Design your plug-in and the .syntax of the External 
functions with your audience in mind. 

Since the Feature String ID is vital to your plug-in, you’ll 
want to register it with Apple and FileMaker, Inc. Details of 
plug-in registration are included with the API package in the 
FileMaker Developer Edition. 

If you have ever written a plug-in, a Desk Accessory, or 
a Driver, you will find that writing a FileMaker Pro plug-in is 
extremely simple. 'Ihe details in this article concerning the 
API itself will probably be enough to get you on your way. 
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If you have never written a plug-in it is strongly 
recommended that you re-use the sample plug-in projects 
that come with the API. Walking a programmer through 
creating a FileMaker Pro plug-in from scratch is beyond the 
scope of this article. 

Tiie External Function Plug-in API 

The External Function Plug-in API package contains 
many files, and includes two examples. The best way to 
understand how the individual source and header files relate 
is to examine the examples. The core of the functionality of 
this API is actually quite simple. 

The API includes a programming overview (“EFP 
Documentation.pdf’) targeted at experienced programmers 
who also know FileMaker Pro. It outlines details relevant to 
the differences between a FileMaker Plug-in and other plug¬ 
ins. It covers only specifics that wouldn’t be part of the 
creation of a “typical” plug-in. It is not intended to be a 
“How-to” on writing plug-ins. 

The “FMFlags.h” header file contains used compiler 
directives to control code compilation. Since the API supports 
both Macintosh and Windows plug-ins on more than one 
compiler, this file allows you to have one set of source code 
files that will compile in all cases. Do not alter this file. 

The “FMExtern.h” and “FMExtern.c” files define the 
parameter block and some shared function calls. The 
function calls are needed to, among other things, manipulate 
the “parameter” and “result” handles contained in the 
parameter block that your plug-in will use. 

In the FMExtern.h file, you will notice the call-back 
functions for memory operations are defined. Below that, is 
the definition of the different kinds of plug-in events sent to 
the plug-in. 

typedef eiiura { kFMXT_Init. kFMXT_Idle. kFMXT_lnternal1. 

kFMXT_Rxternal. kFMXT_Shutdown. 
kFMXT_DoAppPreferfinces, kFMXT_Internal2 ) 
FMExternCallSwitch; 

There will be an item in the parameter block that will be 
equal to one of these values. The “Internal” values are 
reserved items. When your plug-in receives control from the 
FileMaker Pro host program, it will be under one of the 
following conditions. 

• kFMXTJnit 

This indicates that your plug-in is being loaded during 
the initialization of the FileMaker Pro application. This 
occurs shortly after the user launches the application. 

• kFMXTJdle 

This indicates that your plug-in is being given some 
processing time, but is not being explicitly used by the 
database or user. If die appropriate flag in the Feature 
String of tlie plug-in is not set, your plug-in will never 
receive this event. 


• kFMXT.External 

This indicates that one of the functions of your plug-in is 
being explicitly used by tlie database or user, and needs 
to return a value. If the appropriate flag in the Feature 
String of the plug-in is not set, the functions of your 
plug-in will not be accessible to the database or user. 

• kFMXT_DoAppPreferences 

This indicates that the user has just clicked on the 
“Configure” button in the plug-in management dialog 
within FileMaker Pro. Your plug-in can now present its 
own preferences dialog box. If the appropriate flag in 
the Feature String of the plug-in is not set, the 
Configure button will be grayed out and your plug-in 
will never receive this event. 

• kFMXT_Shutdown 

This indicates that the FileMaker Pro application is 
about to terminate normally. This allows your plug-in 
to do the appropriate cleanup, if needed. 

Immediately below the FMExternCallSwitch definition is 
the type definition for “FMExternCallStruct”. The 
FMExternCallStruct is the structure of the parameter block for 
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the External function API. “FMExternCallPtr” is defined as a 
pointer to that struct. A global variable “gFMExternCallPtr” is 
then defined as a FMExternCallPtr. 

I'hese structures are the “meat and potatoes” of the 
communication between your plug-in and FileMaker Pro. 
Nestled within this structure are two innocent looking variables 
of type long. They are ‘‘paramS” and “result”. 'I'he variable 
“param3” is actually the parameter data that was passed to the 
External function from the calculation formula in FileMaker 
Pro. It is referred to as “parameter” in some of the functions. 

Variables you will coerce to “FHandle” variables in your 
plug-in code. A Fhandle is simply a handle to unsigned 
character data. There is no need for a length byte or null 
terminator for this string as the size of the handle is the size 
of the string. Since External functions can only return 
text/string data, the data you read from “param3” (or 
“parameter”) and the data you put into “result” must be text, 
or a textual representation of a number. 

The “FMTemplate.c” or “FMExample.c” files are 
examples of what the main file should look like. Note that 
they both define the main/entry point function for the 
various environments (PPG, 68k, or x86) a plug-in can be 
compiled for. 

Inside the Main entry point, there is a switch statement 
that allows the plug-in to determine the condition under 
which control is passed to it, so that it may act appropriately. 

switch (pb >whichCall) I 

The variable “pb” is simply a local variable that was assigned 
to l:>e equal to gFMExternCallPtr. Everything else within these files 
is non-essential to the API and sjxrcific to your plug-in. 

Since the API is considered proprietary information, you 
cannot republish any information in any of the files other than 
the “FM'lemplate.c” and “FMExample.c” files. 

The Fhij. Example Plug-in 

Provided with the API are a “Template” plug-in and a 
“Full Example” plug-in. The “Template” is a shell project with 
two functions typically used only by programmers. 

The “Full Example” plug-in was designed as an example 
of what a “full blown” plug-in would look like. While it 
doesn’t illustrate every possible use of a plug-in, it does have 
many subroutines that are well suited as External functions, 
or in designing them. It also demonstrates a rudimentary 
preferences dialog. 

Let’s say the FileMaker Pro user has installed the 
compiled Full Example plug-in and created a calculation field 
that refers to one of the functions, Xpl-BigPi. The reference to 
the External function would appear in the calculation formula 
as something like “...External(“Xpl-BigPi”, 

“External” signals FileMaker Pro that it must locate the 
function “Xpl-BigPi” in one of the loaded External Function 
Plug-ins. Once located, the External function passes the 
contents of the second parameter as a handle. In this case, the 


handle will have a size of zero. The contents of this parameter 
are stored in the contents of “param3” for the plug-in. 

Within the main/entry point, the plug-in will be notified 
that one of its External functions is being used, and that it 
must call the appropriate function. The sample plug-ins use 
a handler named “Do.External”. 

case kFMXT_External: 

Do_External(pb->pann2. (FHandlc)(pb >parm3), 

(FHandle)(pb >rGsult)); 

break; 

Note that the handler has three parameters (obtained 
from the parameter block). The first parameter is the index 
number of the plug-in. The first function is index number 
zero. Xpl-BigPi is the second function, so the index number 
will be one. 

Going to the source code, the “Do_External” handler looks 
something like this: 

// Received a message that some calc depends on one of the External functions in this 
// plugin, so perform the appmpriale function and return the results back to FileMaker 
// Pro (FMP). 

static void Do_External(long functionid, Fllandle parameter, 
FHandle result) I 

switch (fund ion Id) I 

#if DEBUG_VERSION 

case 0: 

// Since we’re debugging, let’s have a debug ftinction to access from FMP in 
// place ofThtsVersion. 

// In FMP, we’ll still have to “pretend" we’re using the version function 
// "ThisVersion", but we’re aeiually calling a different function in our 
// plugin. 

DebugPlugin (parameter, result); //not PluginVersion 
break; 

#else 

case 0: 

//This is the “shipping" vi*rsion of our plug-in, so let’s disable the debug 
// hinct and use the pn)|KT'nilsVcrsion function -> PluginVersion 
PluginVersion(parameter, result); 
break; 

#endif 

case 1; // pi = Xpl-BigPl 
funct PI(result); 
break; 

case 2: //format a numlxT = Xpl-Fomiat 
funct_Format(parameter, result); 
break; 

case 3: // number to words = Xpl-NiimericalWords 
fund Niim2Words(paranioLer, result); 
break; 

default: 

// Beep, niis plugin is being sent a mes.sage to execute a function 
// tliat doesn’t exist in this plug-in. (This could be due to a plug-in 
// installed with the same name as ours, with a bigger number of 
// functions.) 

//if FM_CPU_X86 
MessageBccp(O); 

//else 

SysBeep(l); 

//end if 

1; r switch 7 
) r Do_Extemal V 
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The function with the index of one that is executed by 
this function is “funct_PI(result)”. We pass on the result handle 
that this handler function received from the main/entry point. 
Remember that the parameter was in the original 
calculation formula. 

The pi function doesn’t need a parameter, so even if the 
handler passed on the parameter handle, it wouldn’t use it. 
However, funct_Pl does change the result handle to k_PI 
(“3!14159265358979\0”). It is defined as a null-terminated 
string in case the programmer will use it elsewhere. 
k_PlLength represents the length of the string we will actually 
return to FileMaker Pro (i.e. l6). 

The exclamation point is a placeholder that will be 
replaced with whatever decimal point character is 
appropriate for the country the plug-in is being used in. 

// Returns pi to the I4th digit (past decimal), as hardcoded in the defines file 
// “FMExample.h" 

static void funct_PT(FHandlc result) { 

FMX_SelHandlGSize(result, k_PlLength); 

if (FMX_MemoryError0 =0) ( 

#if FM_CPU_X86 

lstrcpy((LPTSTR)‘result, k_PI); 

//else 

BlockMoveData(k_PI, ‘result, k_PILength); 

//end if 

(‘result)[1] = decimalSepCH; 

// Make sure to substitute that'!’ in our fn value to the 
// acceptable decimal separator tor numbers in this 
// countr}^ 

} //end if 
) //funct_PI 

When control is passed back to FileMaker Pro, the result handle 
in the parameter block is the value of “External(“Xpl-BigPi”,””)”. 

Although the other functions do much more complicated 
things, this is essentially how all External functions will 
behave. The rest is up to your imagination! 

Considerations 

Debugging code resources or shared libraries is not a 
simple task. However, if you use DebugStrO and the 
“DisplayMessage” function, you can do rudimentary 
debugging very easily. DebugStrO is a function defined in 
the Universal Headers, which allows you to display a Pascal 
style string in a low-level debugger. “Display Message” is a 
function that is defined in the sample plug-in projects. 

Tf you are having trouble, you might want to consider 
pasting your plug-in functions into a console project and 
debug it as an application. 

The API is provided only in a C/C++ format. If you plan 
on using another programming language, you will have to 
convert the API from C to the other language. 

The Ain is designed to be cross-platform (both Mac OS 
and Windows). Tf your plug-in is going to be Mac OS only, 
you can feel free to strip out all the compiler directives for 
readability. It is recommended to keep them in, however. 


Many FileMaker Pro database solutions are cross-platform. 

In addition to having cross-platform compiler directives, 
the Full Example plug-in takes into consideration 
international users. If you are manipulating numbers, dates 
or monetary amounts, it is strongly recommended that you 
also take international users into consideration. The Internet 
has significantly increased the market for products that are 
friendly to international users. 

Some advanced plug-ins will rely on resources. Make 
sure to set and restore the current resource file to avoid 
getting a resource from another plug-in. Also, use resource 
IDs only in the range between 23,000 and 24,999. 

While you own the code you create, you should be 
careful not to release or publish any files that include code 
from the External Function Plug-in API. You should also treat 
your plug-in as a separate software product with its own user 
license agreement and provisions for technical support. 
FileMaker, Inc. docs not warrant the usability of third-party 
plug-ins, nor provide technical support for using them. 
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PROGRAMMER'S 

CHALLENGE 


by Bob Boonstra, Weslford, MA 


Sphiire Packing 

This month we’re going to help yon recover from the clutter 
that might result from the holiday season. Imagine tiiat your post¬ 
holiday household is filled with gifts, all of which have to be put 
somewhere. Imagine further that those gifts include sports 
equipment given to your children, or parents, or siblings, or 
grandchildren, as the case may l^e. And finally, imagine that tlie 
sports equipment includes a collection of balls of various sizes - 
basketballs, baseballs, soccer balls, beach balls, etc. (OK, if I’ve 
stretched your imagination to the breaking pc^int, think of some otlier 
reason you might have a huge collection of spherical objects.) We’ve 
got to find somewhere to store all of those balls, and space is ai a 
premium. Fortunately, we also have a very laige collection of lx)xes 
of various sizes, so many, in fact, that you can count on finding a 
lx)x of the exact size that you might need. In keeping with our desire 
for a few less difficult problems, your Challenge is to pack the balls 
into tlie smallest box prxssible, so that we can store tliern efficiently. 

The prototype for the code you should write is: 

#if defined(_cplusplus) 

#if defined (_cplusplus) 

extern "C" f 
//end if 

typedef struct Position { 

double coordinate[3]; /* coordinate[0]=Xposition, Ilj==Y, t2)==Z 7 

) Position: 

void PackSpheres( 

long numSpheres, /* input: number of spheres to pack V 

double radius f ], r input: radius of each of numSphcrcs spheres 7 
Position location f ] /* output: location of center of each sphere 7 

); 

//if defined (_cplusplus) 

) 

//end if 

Your PackSpheres routine will be given the number of balls 
(numSpheres) to be packed away, along with the radius of each 
of those spheres. The task is simple. Arrange the collection of 
balls into a rectangular parallelepiped (“box”) such that no ball 
intersects any other ball (i.e., the distance between the centers of 
any two balls is greater than or equal to the sum of their radii). 
PackSpheres returns back the coordinates of the center of each 
ball in the location parameter. Your objective is to minimize the 
volume of the box that contains all the balls, where tlie extent of 
the box in each dimension (X, Y, and Z) is determined by the 
maximum and minimum coordinates of the balls, considering 
both the location of the center of the ball and its radius. 

While you must ensure tliat tlie balls do not intei'sect, you need 
not ensure that the balls touch. In our storage room, boxes of balls 
can contain balls tliat levitate in the open space between other balls. 


The winner will be the solution that minimizes the volume 
of the box containing all the balls, plus a penalty of 1% of 
additional storage volume for each millisecond of execution time. 

This will be a native PowerPC Challenge, using the latest 
CodeWarrior environment. Solutions may be coded in C, C++, 
or Pascal. 

Three Months Ago Winner 

Congratulations to Pat Brown (Staunton, VA) for 
submitting the winning .solution to the October Hearts Challenge. 
Pat’s solution beat the second-place entry submitted by Tom 
Saxton and “dummy” entries that rounded out a tournament of 
four players. Pat’s solution was both the faster of the two and the 
more successful at avoiding point cards, capturing approximately 
one third fewer points than Tom’s solution. 

Pat’s strategy was fairly simple. His pa.ssing strategy is to pass 
the three highest cards in his hand. By not including a low heart in 
the pa.s.s, this strategy can aid a shoot attempt by an opponent, as 
well as being dangerous if it passes the queen of spades to the left. 
When leading, the playing .strategy is to force out the queen of 
spades as quickly as po.ssil)le, unle.ss of course he has the queen. 
Wliile he docs not attempt to “shoot the moon”, he is watchful for 
attempts by other players to shoot, and holds on to high cxirds until 
any potential shoot is spoiled. Otherwi.se, Pat tries to play the 
highest legal card tliat Ls lower tlian tlie current trick leader. 

Tom submitted two solutions, a simple one (used in the 
tournament at I’om’s request), and a more .sophisticated (but less 
successful) one. The simple .solution also tries to avoid taking 
tricks and does not attempt to shoot. It is a little more clever in 
selecting the pass, in that it tries to create a void if po.ssible. It 
does not keep track of who might lie attempting to shoot, and 
therefore docs not attempt to stop them. 'Ibm’s second player 
keeps track of who is void in what suits and tries to shoot when 
it has a strong hand. However, it isn’t (juite perfected, and does 
much worse in a tournament than the first player. 

I’ve included a Point Comparison chart that helps explain 
the performance of the two players, 'fhe vertical bars indicate the 
number of hands in which each player captured the number of 
fioints shown along the horizontal axis. You can see that Pat’s 
solution was slightly more successful at capturing fewer dian 4 
points in a hand, very succe.ssful at avoiding Ix'ing stuck with the 
(|ueen of spaces, and extremely effective at capturing fewer than 
20 points in a hand. The line graphs show the cumulative effect 
of the respective strategies on the .score. 

The table below summarizes die scoring for Pat and Ibm’s 
Hearts entries. Tlie teams played a total of 24 matches, consisting of 
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over 25000 hands of 13 tricks each. The Total Points column in the 
table lists the number of hearts captured during all of tliose tricks, 
plus 13 points for each Queen of Spades, and -26 points for each 
shoot. The table shows the number of nicks “won” by each player, 
and tlic number of times each successfully “shot the moon”. You 
can see that Pat’s winning solution did not attempt to shoot, and 
was very successful at avoiding being stuck with all of the point 
cards. Although not shown in the table, tlie less-than-intelligent 
“dummy” players “shot the moon” more often than eitlier Pat or 
Tom. This was a consequence of their simplistic “strategy” for not 
taking points, which led tliem to hold on to liigh cards longer than 
a more sophisticated player would have done. Also shown in tlie 
table are the execution time of each solution in milliseconds, the 
total score, including the penalty of one point per millisecond of 
execution time, and the code and data sizes. As usual, tlie number 
in parentheses after tlie entrant’s name is the total number of 
Challenge points earned in all Challenges prior to this one. 


Name Ibtal 

Ificks 

Shoots 

lime 

Score 

Code 

Data Points 

Won 


(msec) 

Size 

Size 

Pat Brown 

94775 

59703 

1 

833 

95608 

3152 



398 



Tom Saxton (49) 

157105 

80902 

67 

1230 

158335 

2548 



72 




Top Contestants 

Listed here are the Top Contestants for the Programmer’s 
Challenge, including everyone who has accumulated 20 or more 
points during the past two years. The numbers below include 
points awarded over the 24 most recent contests, including 
points earned by this month’s entrants. 


Rank Name Points 

Rank Name 

Points 

l.Munter, Ernst 

204 

10.Nic:olle, Ludovic 

34 

2. Saxton, Tom 

59 

11.Lewis, Peter 

31 

3. Boring, Randy 

56 

12.Hart, AJan 

21 

4. Mallett, Jeff 

50 

13.Antoniewicz, Andy 

20 

5.Rieken, Willeke 

47 

l4.Brown, Pat 

20 

6, Cooper, Greg 

44 

15.Day, Mark 

20 

7. Maurer, Sebastian 

40 

l6.Higgins, Charles 

20 

8. Hcithcock, JG 

37 

n.Hosteller, Mai 

20 

9. Murphy, ACC 

34 

IS.Studer, Thomas 

20 


Here is Pat’s winning Hearts solution: 

MyHearts.c 

Copyright © 1998 Pat Brown 

#include "Hearts.h" 

* Hearts.c 

* Author: Pat Brown 

*Trivia: there are 5.36447377655x10'^28 different ways that a deck can be dcalcd 

* out for a game of Hearts. 

7 

//define gMAX 52 

//define gMIN 1 

//Just the relative rankings, 1..52. 

// Can be referenced casil>^ using spot and suit value. 

r 

2C,2D,2S,3C,3D,3S,4C,4D,4S,5C,5D.5S,6C,6D,68,211,311,411, 
5H,6H,7C,7D,7S,8C,8D,8S,9C,9D,9S,7H,8H,9H,10C,10D,10S, 

JC JD JS,QC,QD,KC,KD,AC, AD, 1 OH JH,QH,KS,AS,KH, AH,QS 

7 

static const int gCardValue[5][14] = 

{ 

[0. 0. 0, 0. 0. 0, 0. 0, 0. 0. 0. 0, 0. 0). //NoSuil 

(0. 3. 6. 9,12.15.22.25,28,35,38.52.48,49), //Spade 

{0.16,17,18,19,29,30,31.32.45,46.47,50,51), //Heart 

(0. 2. 5. 8.11.14,21.24.27.34.37,40.42.44), //Diamond 

{0. 1. 4. 7,10.13.20.23.26.33.36.39.41.43} //Club 

1 : 

inline int getCardValue{theSuit, theSpot) 

{ return gCardValue[theSuit][theSpot]; ) 

inline UIntl6 NEXTSEAT(UIntl6 theSeat) 

( return (theSeat+l)%4; ) 


Prototypes 

inline static SIntl6 findThisCard(const Card theCards[13], 
const Suit theSuit, const Spot theSpot); 
static UIntl6 findHighestLimitCard(const Card theCards [13], 
const int uLimit); 

static UIntl6 findLowestLimitCard(const Card theCards [13], 
const int iLimit); 

static UIntl6 findHighestIndexLimitCard(const Card 
theCards[13], 

const UIntl6 valid[13], const int numValid, const int 
uLimit); 

static UIntl6 findLowestlndexLimltCard(const Card 
theCards[13], 

const Ulntl6 valid[13], const int numValid, const int 
ILimit); 

static int findValidCards(const Card theCards[13], 
const Suit theSuit, UIntl6 validCards[13]); 


There are three ways to earn points: (1) scoring in the top 
5 of any Challenge, (2) being the first person to find a bug in a 
published winning solution or, (3) being the first person to 
suggest a Challenge that I use. The points you can win are: 


Lst place 20 points 

2nd place 10 points 

3rd place 7 points 

4th place 4 points 

5th place 2 points 

finding hug 2 points 

suggesting Challenge 2 points 


inline UIntl6 findHighestCard(const Card theCards [J3]) 

{ return findHighestLimitCard(theCards,gMAX); ] 
inline UIntl6 findLowestCard(const Card theCards[13]) 

{ return findLowestLimitCard(theCards,gMIN); ) 
inline UIntl6 findHighestIndexCard(const Card theCards[13], 
const UIntl6 valid[13], const int numValid) 

{ return 

findHighestIndexLimitCard(theCards,valid,numValid,gMAX); ) 
inline IIIntl6 findLowestlndexCard(const Card theCards [13], 
const UIntl6 valid [13], const int numValid) 

( 

return 

findLowestIndexLimitCard(theCards.valid.numValid.gMIN); 

) 
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Ciloba] variables 

static UIntl6 myScat; 

// hasPoinis is a bitfield of which players have 
// taken points in iliis hand 
static int hasPoints; 

// another bitfield of what suits I’m cutting 
static int cuttingSuit; 

static int tryToSpoil; 

runningTotal keeps track: of “points” for each player 
in a hand.Thesc aren’t real points, but a key to 
watch for someone trying to puli a sweep. 

If someone gets more than six hearts, or the queen of 
spades and three hearts, they may be trying to sweep 
(unless someone el.se has points). 

««««««»«»*«•»*•»«•**««>««««««:««*««»««#**•**«*»««**«»*»«*j 

Static ini runningTotal[4]; 

static Boolean blackLadyInHand; 
static Boolean blackLadyPlayed; 
static Boolean heartsBroken; 

Required functions 


InitTournament 

pascal void InitTournament(const UIntl6 numPlayers, 
const UIntl6 gameEndingSeore) 
t 

return; 

) 


TnitGame 

pascal void InitGame(const UInt32 playerID[4], 
const UIntl6 yourSeat) 

{ 

mySeat = yourSeat; 

) 


SelectPass 

pascal void SelectPass(const Card dealtlland[13]. 

const Pass passDirection. UIntl6 passedCards[3]) 

I 

int i, top. newtop; 

// Inii globals at the start of a hand. 

blackLadyPlayed = heartsBroken = 

tryToSpoil = hasPoints = cuttingSuit = 

runningTotal[0]“runningTotal[Ij“runningTotal[2]“runningTotal[ 

3] 

“ 0 ; 

if (passDirection != kNoPass) 

{ 

top = gMAX; 

for (i=0; i<3; i-H-) // get the three highest canls 

( 

newtop “ passedCards[i] “ 

findHlghestLimitCard(dealtHand, top); 
top " getCardValue(dealtHand[newtop].suit, 
dealiHand [newtop] . .spot) -1; 

) 

} 


Playlrick 

pascal void PlayTrick(const UIntl6 trickNumber, 

const UIntl6 trickLeader, const Card yourHand[13]. 
const Card cardsPlayed[4]. UIntl6 *yourP]ay) 

( 

UIntl6 validCardsll3j, myCard; 
int niun, i; 

Suit leadingSuit; 

Spot what.sTaking; 

UIntl6 whosTaking; 

Boolean pointsTaking; 


if (trickNumber = 0) 

( 

// see if IVe been passed the Queen of Spades 
blackLadyInHand “ 

(findThisCard(yourHand, kSpade, kQueen) >“ 0); 
if (trickLeader ““ mySeat) 

{ 

‘yourPlay = findThisCard(yourHand, kClub, k2); 
return; 

1 

else 

goto NOTLEADING; 


if (trickLeader = mySeat) 

I 

// try to force the Queen of Spades (unless I have it) 
if (!blackLadyPlayed && !blackLadyInHand) 

( 

if ( 

(num = findValidCards(yourHand, kSpade, validCards)) 1“ 0) 

I 

myCard = findLowestIndexCard(yourHand, validCards. num); 
// don’t play higher than the Queen 
if (yourHand(myCard).spot < kKing) 

[ 

*yourPlay “ myCard; 
return; 

) 

) 

) // (IblackladyPlayed && IblackladylnHand) 

num = findValidCards(yourHand, kNoSuit, validCards); 

“yourPlay = findLowestIndexCard(yourHand, validCards. num); 

return; 

1 // if (trickLeader == myScat) 

NOTT.EADTNG: 

leadingSuit = cardsPlayed[trickLeader].suit; 
num=0; 

// this is faster than scanning yourHand cvciy time 
if ((cuttingSuit & (1 << leadingSuit))) 
goto CUTTING: 
if ( 

(num = findValidCards (yourHand. leadingSuit, validCards) )=1) 

{ 

// only one card wc can play 

‘yourPlay = validCards[0]; 
return; 

) 

if (num = 0) 

I 

cuttingSuit |“ 1 « leadingSuit; 
goto CUTTING; 

1 

if (num ““ 0) 

( 

CUTTING: 

// we’re cutting this suit 

if (trickNumber ““ 0) 

( 

// Can’t play points on the first trick. 

// 51 keeps us from playing the Queen of Spades. 

num “ findValidCards(yourHand. kNoSuit, validCards); 
‘yourPlay = 

findHighestIndexLimitCard(yourHand, validCards, num, 51): 
return; 

) 

if (!tryToSpoil) 

‘yourPlay = findllighestCard(yourHand); 
else // Save the liigh cards to spoil a sweep. 

‘yourPlay “ findLowestCard(yourHand); 
return; 

1 //if(num = 0) 

// See who’s winning this trick so far. 
i = trickLeader; 

pointsTaking = leadingSuit = klleart; 
whatsTaking “ kNoSpot: 
while (i !“ mySeat) 
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( 

if ( (cardsPlayed[i].suit == kSpade) && 

(cardsPlayed [i].spot == kQueen)) 
pointsTaking = true; 
if (cardsPlayed[i].suit = leadingSuit) 

( 

if (cardsPlayed[i].spot > whatsTaking) 

{ 

whatsTaking = cardsPlayed[i].spot; 
whosTaking = i; 

} 

} 

else // (cardsPlayed[i].}juit != leadingSuit) 

{ 

pointsTaking |= (cardsPlayed[i].suit == klleart); 

} // if(cardsPlayed[i].suit == leadingSuit) else 
i = NEXTSEAT(i); 

} // while (i != myScat) 

if ((leadingSuit == kSpade) && blackLadyInHand) 

{ 

myCard = findThisCard(yourHand. kSpade. kQueen); 
if (whatsTaking > kQueen) //dump it on King orAcc 
{ 

*yourPlay = myCard; 
return; 

I 

else // don’t play the Queen of Spades 

{ 

for (i=0;i<num;i++) 

1 

if (validCards[i] = myCard) 

( 

while (++i < num) 

validCards [i-1] = validCards[i]; 
num-; 

) 

) //for (i=0;i<num;i-H-) 

} // if (whatsTaking > kQueen) else 
1 // if ((leadingSuit == kSpade) && blackLadyInHand) 

if (trickLeader = NEXTSEAT(i)) //playing last 
{ 

if (!pointsTaking) 

( 

if (try To Spoil) // don’t waste the higli cards 
*yourPlay = 

findLowestIndexCard(yourHand, validCards, num); 

else 

‘yourPlay = 

findHighestIndexCard(yourlland, validCards, num); 
return; 

) 

else 

{ 

if (tryToSpoil = (1 << whosTaking)) 

1 

myCard = findHighestIndexCard(yourHand, validCards, num); 
if (yourHand [myCard] .spot < whatsTaking) //we can’t take this trick 
myCard = findLowestIndexCard(yourHand, validCards, num); 
*yourPlay = myCard; 
return; 

} 

else // someone else is spoiling the sweep 

{ 

*yourPlay = 

findHighestIndexLimitCard(yourHand, validCards, num, 
getCardValue(leadingSuit, whatsTaking)); 

return; 

} 

] // if(Ipointsfaking) else 
] // if (trickLeader == NEXTSEAT(i)) 
if (tryToSpoil) 

{ 

myCard = findHighestIndexCard(yourHand, validCards, num); 
if (yourHand [myCard] . spot < whatsTaking) // we can’t take this trick 
myCard = findLowestIndexCard(yourHand, validCards, num); 
*yourPlay = myCard; 
return; 


// Standard behaviour 

// Play the highest card under the current highest card. 


‘yourPlay = findHighestIndexLimitCard(yourHand, validCards, 
num, getCardValue(leadingSuit, whatsTaking)); 

return; 

) 


TrickResulis 

pascal void TrickResults(const Card lastTrick[A], 
const UIntl6 trickWirmer) 

( 

// Keep track on who has what points so we can watch for a sweep, 
int i; 

int points = 0; 
int whoWon; 

for (i=0; i<4; i++) 

{ 

switch (lastTrick[i].suit) 

( 

case kSpade: 

if (lastTrick[i].spot = kQueen) 

{ 

// not 13, we trigger a sweep when “points” hit 7 
points += 4; 
blackLadyPlayed = true; 
blackLadyInHand = false; 

) 

break; 

case klleart: 
pointS++; 

heartsBroken = true; 
break; 

1 

1 //for (i=0; i<4; i++) 
if (points = 0) 
return; 

points = runningTotal[trickWinner] += points; 
whoWon = 1 << trickWinner; 
hasPoints |= whoWon; 
if (tryToSpoil) 

{ 

if (whoWon != tryToSpoil) 
tryToSpoil = 0; 

} 

else //(ItryToSpoil) 

{ 

if (trickWinner != raySeat) 

tryToSpoil = ((hasPoints = whoWon) && (points > 6)) 


HandResulls 

pascal void HandResults(const SIntl6 pointsThisHand[4], 
const SInt32 cumPoints[4]) 

{ 

return; 

} 

My functions 


findThi.sCard 

Return the index of a particular card, 
or -1 if it’s not there. 

inline static SIntl6 findThisCard(const Card theCards[13], 
const Suit theSuit, const Spot theSpot) 

{ 

SIntl6 c = -1. i = 13; 

while ((c<0) && i ) 

( 

if ( (theCards[i].spot == theSpot) && 

(theCards[i].suit = theSuit)) 
c = i; 

] 

return c; 
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These next few functions find cards based on a limit, 
(it’s an iiK'lusive limit) 

If there arc no cards within the limit, then call 
the opposite function. 


findHighestUmitCard 


static UIntl6 findHighestLimitCard(const Card theCards[13]. 

const int uLimit) 

I 


int i » 13; 

int points, theValue = 0; 

SIntl6 theCard = *1; 


I 


if (theCard < 0) 

theCard = findLowestTndexLlmitCard(theCards, valid, numValid, 

uLirait); 


return theCard; 


findLoweslIndexIimilCard 

static UIntl6 findLowestlndexLimltCard(const Card theCards[13]. 
const UIntl6 valid[13], const int numValid, 
const int ILimit) 

{ 


int i = numValid; 

int points. theValue “ 99; 

SIntl6 theCard = -1; 


while (i-) 

I 

points = getCardValue(theCards[i].suit, theCards[i].spot); 
if ((points > theValue) && (points <= uLimit)) 

theCard = i; 

if (uLimit (theValue = points)) 
return theCard; 

) 

} 

if (theCard < 0) 

theCard = findLowestLimitCard(theCards, uLimit): 
return theCard; 


findljowestLimitCard 

static UIntl6 findLowestLimitCard(const Card theCards[13], 
const int ILimit) 

( 

int i “ 13; 

int points, theValue = 99; 

SIntl6 theCard " 1; 

while (i-) 

I 

points * getCardValue(theCards[i].suit, theCards[i].spot); 
if ((points < theValue) && (points >= ILimit)) 

theCard = 1; 

if (ILimit = (theValue * points)) 
return theCard; 

I 

) 

if (theCard < 0) 

theCard * findHighestLimitCard(theCards, ILimit); 
return theCard; 


findHiglicsilndexLimiiCard 

Index functioas u.se an array of valid card indexes. 

***•”•••"* INHNITF. REajRSlON WARNING •*««««« 

Do not call these functions with numValid = 0!!! 

• •«»***««*«*t*««**«**«M*««4***««M*«****«*«*»««*»**^ 

Static UIntl6 findHighestIndexLimitCard(const Card 
LheCards[13J, 

const UlntlG valid[13], const int numValid, 
const int uLimit) 

{ 

int 1 - numValid; 

int points, theValue “ 0; 

SlntlG theCard = -1; 

while (i-) 

I 

points = getCardValue(theCards[valid[i]].suit, 

theCards[valid[i]].spot); 
if ((points > theValue) && (points <= uLimit)) 

I 

theCard - valid[i]; 
if (uLimit == (theValue = points)) 
return theCard; 

1 

) 


while (i-) 

( 

points = getCardValue(theCards[valid[i]J.suit, 

theCards[valid[i]].spot); 
if ((points < theValue) && (points >“ ILimit)) 

theCard = valid[i]; 
if (ILimit = (theValue = points)) 
return theCard; 

1 

} 

if (theCard < 0) 

theCard = findHighestIndexLimitCard(theCards, valid. numValid, 

ILimit); 

return theCard; 


findValidCards 

Fill an array with indexes to cards of a particular .suit. 

Returns the number of valid cards (the size of the array) 

Passing kNoSuii will fill the list depending on whether 
hearts can be played now. 

static int findValidCards(const Card theCards[13], 
const Suit theSuit. UlntlG validCards[13]) 

I 

UlntlG i; 

int num = 0; 

if (theSuit =* kNoSuit) 

( 

if (heartsBroken) 

( 

for (i-0: i<13; i++) 

if (theCards[i] .suit !- kNoSuit) validCards[nunrH-J = i; 

1 

else //(IheartsBroken) 

I 

for (i=0; i<13; 1++) 

( 

if ( (theCards[i].suit != kHeart) &G 
(theCards[i].suit !- kNoSuit)) 
validCards[num++] " i; 

} 

if (num = 0) // Nothing but hearts left to play, 
for (i=0; i<13; i++) 

if (theCards[i] .suit != kNoSuit) validCards [rmm-H-j = i; 

) 

} // if (heart.sBroken) else 

1 

else // (theSuit != kNoSuit) 

( 

for (i=0; i<13: i++) 

I 

if (theCards[i].suit theSuit) 
validCards[num++] " i; 

) 

1 

return num; 

) 

Hi 
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FROM THE 

FACTORY 

FLOOR 


hy Darryl Lovato, Brian Pfister, Peier 'Ihomas, and Dave Mark, ©1998 by Melrowerks, Inc., all rights reserved. 


What’s New at Aladdin? 


'I'his month, the Factory Floor visits with the folks at 
Aladdin. My personal connection to Aladdin began when 
they first introduced Magic Menu, the iconic menu that was 
added to the Finder’s menu bar and allowed you to 
perform a variety of compression operations on the current 
Finder selection. At the time, 1 was blown away by this 
trick and trying to figure out how they did that opened up 
a bunch of new Mac programming doors for me. 

; ■ Darryl Lovato is Alaclclin \7] Chief Technology Office^ 
vatid Board membefi fomto; l3^,l W: d TFyear veteran in, tW 
%igh tech software hitsiness arid an Aladdin co founder: Prierr 
[fo 6pfounding Atdddin, worked as a- S6ftware\ 

Engineer for Dayna Cotnfmmicdliom on ^"Mac Charlie"]^ U] 
PC-Mac Emulator, and FTlOO, a DOS drive fortheMaemtosk^ 
vjbile attending the University of Utah in the Compiler 
. Science Department. During this time Darryl also worked as a 
; consultanty a contractprogmmrner;.anda contrihu^^^^^ editor 
pfMacTechM : ^ 

’ ' Ddrtyl also .worked atffML :Systems;:developing the TMD 
iPascal Compiler; as well m at Apple-Computer, where he 
- worked- on : the Apple JIGS. Finder,, Control Panels, Advanced; 
Disk Utilities products and later worked on the Macinlosh list 
and Macintosh Use cpmputeis: Ijovato also served as the Applei 
11 laisbn to the /^ple htimandriterface group. "" 

Btnan PJlster is the Stuffit Delu^ Lead Engineer PftslpT: 
an atnd soccer player and coinpukir engineer; attended 
the University bf SdntdClura: yhajoririg m Computer* Science:: 
f^Afterwards, Pfister moved to South West Florida to start :his : 
fornpanVr Sofilink, tohere he developed OpenDoc parts. . ' 
;. PflstePs expertise led him to Aladdin Systems to continue- 
Ihis engiheering focus. Over the past yedr^ Pfister' has enjoyed 
\ working on the Macintosh-standard cdmpressiori softuwe; 
hstufflt Deluxe, wbwh many engmeenng aspects in version 5.Qi 
'are.accredtte^l^'^y ■ • - ^ ■. ■.: ■ f ■ :- -: ' ■ ‘ 

: Peter Thomas, 2Si; has imm: many bats fof the Lbree: 
and d half years he's Been uHth Aladdin. He begat i his Career 
;m technical support, hul has also held positions injradeshour 
\ technical management, product demomtrations, and is 
currently a product manager for Aladdin FlashBack, Private i 
File and Aladdin Desktop Magician: 


Dave: How can developers add Stufflt technology to 
their own apps? 

Darryl: Aladdin provides a Stufflt Engine SDK (software 
developer kit), that is downloadable from the Aladdin 
website <http://www.aladdinsys.com/developers/>. The 
original purpose of the engine was to put all the code 
that does compression and decompre.ssion in one 
place, so it wouldn’t be duplicated in all of Aladdin’s 
products. A “side-effect” of this made it possible for 
other developers to call the engine to compress or 
decompress files. Many developers have already 
included this functionality in their products including 
America Online and QUALCOMM. 


Using the Stufflt Engine is actually pretty easy. You 
simply open the engine, pass the files or folders to 
compress or decompress to the engine, and it does the 
rest. I’ve included some sample code that shows how 
simple it really is. The Stufflt Engine SDK also provides 
low-level calls that allow you to do things like walk the 
contents of an archive, etc. 


r SimpleTest.c puts up a dialog box lo allow you lo select a file. It then determines the 
file type and takes appropriate action of stuffing (if tlie selected file is not a .sit file) or 
unstuffing (if the seleaed file is a .sit archive). Modih'ing constants in the code allows 
you to change the stuffing parameters and see their effects. SimpleTest.c demonstrates 
how to use the high level SDK calls. •/ 


It i f ndef 

#include 

^include 

#include 

^include 

//include 

//include 

//include 

//incl tide 

//include 

//include 

//include 

//include 

//include 

//include 

//end If 

//incl ude 


MWERKS_ 

<DGsk.h> 

<Dlalogs.h> 

<DiskTn i t.. h> 

<Errors.h> 

<Events.h> 

<Files.h> 

<Fonts.h> 

<Memory.h> 

<Menus.h> 

<0SEvents.h> 
<StandardFi1e.h> 
<TextEdit.h> 

<Types.h> 

<Windows.h> 

“StuffItEngineLib.h" 
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main 0 

I OSErr err; 

StandardFileReply theReply; 

FSSpec theFSSpec. destSpec, expandedSpec; 

long magicCookie; 

Boolean makeSEA = true: 

// changes these for different actions... 

Boolean encodeBinHcx = true: 

TnltGraf((Ptr)&qd.thePort): 

InitFonts(); 

InitWindowsO ; 

InitMenus 0; 

TEInitO ; 

InitDialogs(OL); 

InitCursor(): 


was about six years old, and didn’t support a lot of 
new technology that has been created since then. The 
new format has the following new features: 

New Stuffit technology provides a 20% compression 
improvement and gives two compression methods, 
“Fast” or “Maximum”. 

Fast is roughly equivalent to the old Stuffit 
algorithm, except that it’s about 20% faster 


StandardGctFile(NULL, -1, NULL, &theReply); 
if (theReply.sfGood) I 

theFSSpec = theReply.sfFile; 

err " OpenSITEngineCkUseExternalEngine.&magicCookie): 
// first we open the engine up 
if (!err && magicCookie) I 
// if we found it - let’s use it! 

// make sure we have the correct version of the Engine 
if (GetSlTEngineVersion(magicCookie) >= 
kl’irstSupportedEngine) I 

short ftype = DetermineFileTypeC&theFSSpec): 

if (ftype = ftype_StuffIt) (//then unstuff it 

UnStuffFSSpec(magicCookie, &theFSSpec. NULL, NULL. 
kDontPromptForDestination. kDontDeleteOriginal, 
createFolder^Smart. kSaveComments. kDontStopOnAbort, 
USIT_confIict_autoRename, textConvert_Smart): 

1 else ( //stuff that .sucker! 

FSSpec arcSpec: 

FSSpecArrayHandle specListH * NewFSSpecList(); 

i f (ftype) ( //this is something we can expand 
ExpandFSSpec(magicCookie. ftype, &theFSSpec, NULL, NULL. 


c r eat eFolder Smart. 

) else { //.stuffit! 
AddToFSSpecList(&theFSSpec 


kDontDeleteOriginal. 
lexLConvcrt_Sraart): 

specListH); 


GetNewArchiveFSSpec(specListH, makeSEA, &arcSpec); 
StuffFSSList(magicCookie, specListH, &arcSpec, NULL. 

kCompressOriginal, kDontDeleteOriginal, 
kDontEncryptOriginal, kResolvcAliases. 
kRecompressCompresed. SIT_conflict_autoRename): 


if (makeSEA) 

ConvertSlT2SEA(magicCookie, &arcSpec): 


} 


if (encodeBinHex) { 

HQXEncodeFSSpec(magicCookie. &arcSpec, NULL, 
kDontDeleteOriginal, kDontAddLineFeeds, 
kDefaultHQXCreator); 

) 


Maximum is [)rand new, and compresses files an 
average of 20% smaller than the old algorithm 

• Multi-Lingual - All strings are stored in Unicode, and 
file names can now be of any length 

• Updated transparent cross-platform file format 
interchange, so it is now more multi-platform. All QS 
file coding information is saved/lranslated/restored 
correctly, regardless of source or target platform, (Mac, 
Windows, Unix). A type/creator extension table also 
maps file types between platforms. 

Stuffit Deluxe now includes full support of IIFS+ on 
the Mac. The create and modification dates are all 
translated correctly and Mac file comments are now 
saved and restored. 

• No more archive file size or number limits 

• In addition to the new file format, the new version 
now supports MacBinary III, OS 8.5, Appearance 
Manager, Archive Via Rename support for .h(|x and 
.bin, and support for MS Outlook Express and 
Mailsmith Support has been added to the Mail 
extension. 

Dave: Can you fill us in on the magic behind your 
True Finder Integration technology? 


DisposeFSSpecList(specListH); 

) 

) 

CloseSITEngine(magicCookie) ; //and finally dose il 
I 

1 

Dave: By the time folks read this, Suifflt 5.0 will have hit the 
streets. What new technologies arc in this release? 

Darryl: The l)iggesi change in Stuffit 5.0 is that for the 
last three years we have been re-writing the STUFFI'I' 
archive file format from the ground up. The old format 


Brian: True Finder Integration ('FFI) is a series of 
components that allow you to manipulate Suiffit 
archives from within the Finder. The TFI Control Panel 
is the heart of these components. TFI has a plugin 
architectural. 

_mpeg.extension”. ”mpg.mpeg”): 

user_pref(“mime.audiCurrently we have 3 plugins 
(MagicMenu”!, ArchiveViaRename"!. and Stuffit 
Browser”!). 

We load the plugins in a 2 step process. TFI does its 
preflighi at INIT time. 'Fhat includes installing the 
appropriate Gestalt Vectors that the individual plugins 
will use to communicate with TFI. TFI then finds all the 
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plugins and reads their individual internal preferences. 
One of these preferences tells TFI when the plug-in 
should be called for its pre-flighting. I’his can be either 
immediately, when Finder launches, or at both times. If 
there is a plug-in that requires a preflight at Finder 
launch, TFI will patch InitDialogs. From within this 
patch I’Fl will call the plugin to initialize itself. 

Fach plugin follows a similar loading procedure. They 
first install a Gestalt vector so that the TFI control panel 
can configure them as needed. They then load the 
necessary code resources and reserve the needed 
memory. Lastly they patch the calls that they need. AVR 
is the simplest, patching only ^Rename. The Browser is 
the most complicated. It patches more than 40 OS traps 
Sl ToolBox traps. MagicMenu is pretty modest, patching 
only the four MenuBar related system calls: 
_DrawMenuBar,_MenuKey,_MenuDispatch and 

_MenuSelect. We use a head patch with DrawMenuBar. 
We head and tail patch the other three. 

Like TFI, MagicMenu has a plugin technology. Its main 
purpose is to determine what is selected in the Finder and 
pass that infonnation to the appropriate MagicMenu 
extension (MME). It is the specific MME that makes the 
appropriate calls to the Stufllt Engine. MagicMenu and its 
plugins communicate through a dispatch routine. 

Dave: What are your plans for Carbon/Mac OS X? 

Brian: It is still too early to commit to Carbon/Mac OS X 
100%. We are keeping a very close eye on it for future 
revisions of our products. We expect a future version 
of Deluxe to be veiy close to 100% carbon compliant 
but since Carbon/Mac OS X development will be 
progressing in time frame parallel to our engineering 
and development we can not expect Deluxe to be 
completely compliant. 

The True Finder integration technologies are a 
completely different challenge, since they are so closely 
tied to the current OS architecture. We have conceded 
that they will recjuire a complete rewrite to work under 
Mac OS X. Given that fact, we intend to look closely at 
Mac OS X and see how we can best fit the functionality 
of TFI into the Mac OS X. This will be better understood 
as Mac OS X evolves over the next year. 

Dave: What can you tell me about your latest 
release of InstallerMaker, V5.3? 

Brian: InstallerMaker has gone through dramatic 
changes in the last year. We began at MacWorld Expo 
‘98, by introducing support for retrieving files from the 
Internet. We also gave installers a face-lift, to provide 


a more modern look and feel. In our 5.0 release, 
following Apple’s Worldwide Developer’s Conference, 
we radically altered the internal structure and handling 
of archives and installers. For the first time, developers 
could set all conditions, package assignments, and 
actions individually to items nested inside folders. We 
also added long overdue support for hierarchical 
packages. InstallerMaker 5.3 solidifies and strengthens 
our earlier work through code optimizations and 
completion of full scripting support. 

InstallerMaker’s Network or Internet support includes 
both FTP and imP file transfers. Developers create 
“Network Install” tasks for the files to be retrieved. 
These tasks consist primarily of the name of the host 
to retrieve the file from and the path leading to the 
file. Developers may optionally choose to configure 
their installers to automatically decode BinHex and 
MacRinary files and decompress Stuffit .sit files and 
.zip files. It’s very easy to use, flexible, and has 
powerful installer technology. 


StoneTable 

You thought it was just a replacement 
for the List Manager ? 

We lied, it is much more I 

Tired of always adding just one more feature to your LDEF or 
table code ? What do you need in your table ? 

Pictures and Icons and Checkboxes ? 
adjustable columns or rows ? 

Titles for columns or rows ? 

In-line editing of cell text ? 

More than 32K of data ? 

Color and styles ? 

Sorting ? 

More ?? 

How much longer does the list need to be to make It worth 
$200 of your time ? 

See just how long the list is for StoneTable. 

Make StoneTable part of your toolbox today ! 

Only $200.00 MasterCard & Visa accepted. 

StoneTablet Publishing 
More Info & demo Voice/FAX (503) 287-3424 

http://www.teleport.com/~stack stack@teleport.com 
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The 5.0 release focused on ihe functionality most 
requested by our customers. InstallerMaker has always 
required conditions, package assignments, and actions 
to be set only at the root level of archives, which 
meant items in folders would always receive the same 
settings as their root parents. This made it difficult to 
create a single installed folder with items installed 
based on many different criteria. Developers had to 
use folder factoring, a process by which multiple 
folders of the same name in an archive are merged 
together during installation, to build these installers. 
Version 5.0 blew away that barrier, so now every 
archive item may be individually assigned different 
conditions, packages, and actions. 

Hierarchical packages were also a big part of the 5.0 
release. We worked hard to make it easy to configure 
for developers and easy to use for their customers. We 
wanted to preserve the original functionality, for 
developers not wishing to use the new support, while 
extending the feature set out for those who did. We 
also shied away from changing the design toward 
things we didn’t like about other installers we have 
seen, which we considered less intuitive and thus less 
user friendly to use. Specifically, we wanted to keep 
the descriptions of packages displaying in the main 
installer window automatically when a user clicked on 
a package name. We also added a selection button with 
a question mark on it next to each package in a 
package list. We wanted to get users connected with 
information as efficiently as possible. 

InstallerMaker 5.3 is a developer’s dream release, 
especially if an automated build system is the goal. This 
relea.se fills out all the nooks and crannies of automatic 
generation of installers through AppleScript. 
InstallerMaker 5.3, with the new native AppleScript 
support in Mac OS 8.5, is a powerful combination for 
supporting an automated build system. We also provide 
a FileMaker Pro database example, used in conjunction 
with AppleScripts, demonstrating a complete 
automated build system. Aladdin u.ses a derivative of 
that example for our own automated build .system for 
our products. The database allows product managers to 
file installer requests that are easily turned into 
automatically generated installers for Aladdin products. 
It’s a really fluid process and quite elegant in how it 
handles our installer needs. 

Dave: I’ve heard about a product called FlashRack. 
What can you tell me about it? 

Peter: Aladdin Flashback provides unlimited Undo’s for 
any application with instant access to all previous 


versions of a document. With Aladdin Flashback, you 
can create, compose, edit and save documents in any 
application without the fear of ever losing their work. 
It recovers previously saved versions of any 
Flashback-protected document, even if the original file 
is lost, damaged, overwritten or erased. It tracks and 
records only the changes made to a document each 
time it is saved, eliminating the need for “Save As....” 

'lb “Flashback” a document, the user simply drags and 
drops the file into the Aladdin Flashback window. Every 
time the file is saved, Flashback u.ses a “differencing 
engine” to compare the current file to the previously 
saved version and captures and records the changes. 
Only the changes between these two files are recorded 
and saved by the Flashback application (under the same 
title with a time and dale stamp), so disk space is 
reduced compared to the conventional “Save As....” 

The Flashback application window lists all the tracked 
files and their versions. To retrieve a previous version, 
the user simply double-clicks on the .selected version, or 
drags it to the desktop. Flashback launches the file’s 
application (if it is not already running) and combines 
the current document with the difference files to 
generate the version the user selected. The file is 
recreated exactly as it was at the time and date indicated. 

FlashRack maximizes efficiency by letting the user set 
the frequency with which it records changes. The user 
can configure FlashRack to track changes whenever a 
document is saved, or whenever it is closed. With 
programs that have an auto-save function. Flashback 
can be set to .save changes every few minutes, instead 
of every in.stant, since many auto-save programs save 
so frequently. Settings can be made on a default basis, 
or tailored to a file or application. 

Hi 


Want to get Mac OS developer 
news delivered to you? 


Subscribe to MacDev-l" 

■tiir 

A subscription form available 
through a link on the MacTech® 
home page at 

< http://www.mactech.com > 
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POWERPLANT 

WORKSHOP 


by John C. Daub, Austin, Texas, USA 


The Ultra-Groovy LString Class 


An introduction to the 
PowerPlant-way of 
working with strings 


Hojlo, World! 

Most software developers have lxx:*n 
working with strings since llicy wrote their 
first program — that’s what “Hello World!” is 
all alx)ut. To facilitate working with strings 
many libraries of utility functions have l^een 
written. Some people have tlieir home¬ 
brewed string libraries, while others utilize 
tliird party libraries or use the libraries 
provided in Standard C and C++. These 
solutions are well and good, but they do not 
always translate very effectively into the 
world of Mac OS. Many of these offerings, 
like the Standard C and C++ libraries, are 
written to work with C-style strings — a 
sequence of characters terminated by a null 
character. But due to the Mac OS T(X)lbox’s 
Pasc:al heritage, strings on the Mac are 
Pascal-style strings — a sequence of 
charaaers preceeded by a length byte wliich 
stores the length of tlie string. Consequently, 
a string library designed to work with 
Pascal-style strings is more valuable to the 
Mac OS software developer. Enter 
PowerPlant’s LString class. 

LString is a C++ abstract base class for 
working with Pa.scal-style strings. It 
provides means for converting strings to 
numbers and numbers to strings; obtain 
strings from numerous sources (characters. 


otlier strings, resources); copy, append, and compare strings; find, 
insert, remove, and replace substrings; and does so in a manner 
that respects the boundaries of Pascal-style strings, lakes 
advantage of the C++ language, makes your code easier to read 
and understand, and mo.st of all is easy and logical to use. 'Ihe 
inherited classes LStr255, TString, and LStringRef provide the 
concTete means for working with strings in a manner very familiar 
to Mac OS software developers, so the learning curve for LString 
is not a steep one. And altliough LString is a PowerPlant class it 
c:an be used independent of the rest of PowerPlant; feel free to use 
it in all of your Mac OS software development efforts. 

If LString sounds good to you, then please read on. In this 
article I hope to provide you with a good overview of what 
LString provides, and illustrate how it will make your software 
development efforts easier. Along the way Ill also show you a 
few of the really c(X)l and groovy power-user features of LString. 
Rut don’t worry! Those power-user features are so easy to use 
tlvat youll be an LString-Warrior before you know it! 

First, Some Background 

Before I go any further, 1 want to make sure that we’re on 
the same grounds of understanding just what a string is, and 
what the differences are Ixrtween the various types of strings. If 
you already understand what the different types of strings are, 
feel free to skip ahead to the next section. 

Simply put, a string is a sequence of characters. This 
sentence is an example of a string. 

A C-style string is an array of characters (char*). The internal 
representation of the string has a null character (^0’) at die end, to 
signal the end of the string, so the amount of storage required for 
the string is one more than the number of characters in the string. 
Due to die use of the null terminator, there is dieoretically no limit 
to the length of a C-style siring, but you must scan the entire string 
to determine the lengdi of die string (the C standard library function 
strlenO can be used to determine the length of die string). So the 
string “Hello, World!” contains thirteen characters, but at least 
fourteen bytes must be allocated to hold that string. 


John C. Daub can’t think of anything snazzy to put in his bio other than 31 Ts a great band to listen to while writing articles. 
If you’d like to contact John, you can do so at h.soi@metrowerks.com. 
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A Pascal-style string is also an array of characters (unsigned 
char*). Like a C-siyle string, a Pascal-style string also requires one 
more than the number of c:haracters in the string for storage. 
However unlike a C-style string (and this is the defining and 
differentiating characteristic) there is no null terminator at the 
end of the string; instead, the first byte of the string is used to 
store a count of the number of characters in the string. You do 
not need to scan the entire length of the string to determine its 
length — you can merely examine the first byte {length hyle) of 
the string. Also unlike a C-style string, a Pascal-style string does 
have a limit; this limit is determined by the number of bytes 
allocated in the unsigned char* array (e.g. unsigned char[256] 
would allow a string up to 255 characters). As a Pascal-style 
string “Hello, World!" still contains tliirteen characters and also 
needs at least fourteen bytes for storage, but the internal 
representation of the string is different. Finally, when specifying 
a Pascal-style string constant, they are typically prefaced by a \p 
to tell the compiler to treat this string as a Pascal-style string (e.g. 
ApHello, World!” would be the actual way to represent our 
example string as a Pascal-style siring). Figure 1 illustrates how 
die internal storage of the “Hello, World!” siring differs as a C- 
style string and a Pascal-style string. 
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Figure L String internal ref^rresentations. 


In Figure 1, each column represents a byte in die array 
(note we start at zero, like any array). The top row is the byte 
count, the middle row is the C-style string, and the bottom row 
is the Pascal-style string. Notice that both string styles require the 
same amount of storage (fourteen bytes). 'Fhe C-style string 
places a null terminator in the last byte (although it looks like two 
separate characters \0 is just a special single character). When the 
string is read in, characters are read one by one until the null 
terminator is reached. If we wanted to find the length of the C- 
style string we would scan the string, starting from the beginning, 
counting each character as we go along until we reach the null 
terminator (this is what strlen does). The Pascal-style string places 
the length of the string in the first byte of tlie array (in this case 
the number thirteen, not “13” as a string or character). When the 
string is read, the first byte is checked for the length, and dien 
exac:tly that many characters are read. If we wanted to find the 
length of the string, we check the first byte (string[0)). 

Bodi styles of strings have their strengths and weaknesses. C- 
style strings can l>e of an arbitrary length whereas Pascal-style strings 
tend to have a more fixed size. C-style strings also have moie 
overhead involved in determining tlie lengdi of tlie string (a function 
call and walking die entire string), but you can fuid die lengdi of a 
Pascxil-style string with a simple check of the length byte. 

On the Mac OS, most strings are Pascal-style strings (since 
the OS and toolbox were originally written in Pascal). To more 
easily represent and identify strings, and provide a simple means 


for defining strings of different lengths, MacTypes.h (formerly 
Types.h) typedefs some arrays of unsigned char’s. The most 
popular version is a Str255, which is an array of 256 unsigned 
char’s. There are others (Str63, Str32, Str15, StringPtr, 
ConstStr255Param — see MacTypes.h for a complete listing), and 
although Str255’s are the most commonly used, the discussions 
in this article apply to any of these type(deDs. The Mac OS can 
also have raw text runs (e.g. TEXT resources, TERec, etc.), and 
you can use C-style strings as well. The only time you are 
“forced” to use a Pascal-style string is when you interact with the 
I’oolbox. If you wish to use C-style strings otherwise, you are 
very welcome to do so, especially if you are more familiar with 
the C Standard Library. Furthermore, the Toolbox provides some 
Pascal to-from C string conversion routines (c2pstr and p2cstr are 
in the Universal Header TextUtils.h ), and even provides C-glue 
routines that are glue routines to T(X)lbox functions that take C- 
style strings as arguments instead (look for the symbol 
CGLUESUPPORTED throughout the Universal Headers). 

But as most Mac OS software development sooner or later 
recjuires you to interact with the Toolbox, most people find it 
easier to use Pascal-style strings all the time (also avoids the 
constant overhead of back and forth conversions). Due to this 
preference is why PowerPlant offers a great .solution in LString. 
Let’s now take a l(X)k at what exactly LString has to offer. 

What’s in There? 

The LString class (and all of tlie classes and material I’ll discuss 
here) can found within the PowerPlant folder of the Metrowerks 
C(xleWarrior Professional product. Specifically within the files 
LString.cp and LString.h. If you own CxxleWarrior Professional, go 
ahead and open up those two files and look over tliem. I don’t 
expea you to necessarily understand what’s in tliere riglit now, but 
give them a look over so you can know what I’m talking about. 
You might also find it handy to refer to the sources as I refer to 
various parts of it .so you can see how all of tills fits togetlier. For 
reference, I am writing tliis article using CodeWiimor Pro 4 and a 
version of LString that should lie part of PowerPlant vl.9.3 (which 
will Ix^ relc'ascxl as public netborne update to Pro 4, and should lx 
available by tlie time you read this article). 

LString 

LString is an abstract base class for working with Pascal-style 
strings. It defines almost all of the flinctionality that one would 
need for working with Pascal-style strings. LString also works to 
take advantage of the C++ concept of overloading. First many of 
the methods arc overloaded to work with many data types (all 
built-in data types, both signed and unsigned, including floating 
[)oinl types; C-.style strings; Pascal-style strings; FourCharCode; a 
Handle to text; other LString objects). Second, many of the 
methods are also offered as operator overloads, were logical, to 
make it easier for you to utilize these methods in your code. For 
example, operator += is the same as the Append() method. LString 
also defines some public methods as static so that non-LString 
objects can take advantage of some commonly needed string 
manipulations like copying and appending. 
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LString is designed to be dean, efficient, and work within 
the boundaries of the Mac OS and the Pascal-style strings utilized 
therein. As noted earlier, MacTypes.h defines different types of 
Pascal-style strings, like a Str255 or a Str63. Due to this ability to 
vaiy in storage length, any time length of string and/or storage 
is relevant to the functionality, LString always requires this 
information be provided, but typically also provides a default 
towards a Str255 as this is the most commonly used type. 
Furthermore, since Mac OS Pascal-style strings have 255 
characters as the upper limit for strings (hence the Str255), 
LString always enforces this upper boundary where appropriate. 
If utilized correctly, LString should alleviate fears and eliminate 
the problem of array boundary overflows. 

Although PowerPlant is a Mac OS-only framework, it does 
try to do what it can to aid those that might Ix} using PowerPlant 
in a non-Mac context sucli as porting your Mac OS-based 
application to Windows. Some LString methods are only 
available under Mac OS (due to their nature), and techniques are 
provided for development environments that might not fully 
understand Mac OS conventions. For example, the traditional 
way to obtain the length of the string is to directly check the 
length byte. But since not all development environments support 
this method of access (of course CodeWarrior does), the 
LString::Length() method is provided as a certain means of always 
obtaining the length of the string. 


As an implementation note, there is only one data member in 
LString: mStringRr. mStringRr is a StringRr which points to your 
Pascal-style string. Note that the acmal storage for the string is not 
part of LString. Without this son of design, neither TString nor 
LStringRef could exist (Til discuss these classes later in the article). 
So does tills mean tliat you always have to alloc:ate your own 
storage for your string? Not at all, as this is the purpexse of LStr255. 

I^tr255 

LStr255 inherits from LString. You can find the declaration 
of LStr255 in LString.h and definition in LString.cp. If the name of 
the class looks familiar to you, this is intended. 'The design of 
LStr255 is to replicate the functionality of a Str255, but with loLs 
of extras. The great pan is an LStr255 can be used almost 
anywhere a regular Str255 is used and in the same manner. 
Funhermore an LStr255 inlierits all of the hinctionality of LString, 
plus it provides the actual storage for the string itself (the 
mString data member) so you do not have to. 

Listing 1: Use of Str255 _ 

Obtain and concatenate two .strings 

To explain a convention used in all listings: any liinction call preceeded by the uttaty 
scope resolution operator (::) specifics tliis symbol is located in the global 
namespace — the same place \iiiere the Toolbox symbols are located.These arc 
Ibolbox calls. Feel free to look them up in Inside Macintosh on the Apple WWW site 
for moit* information and detail. 


AppMaker -More than a GUI Builder 


User Interface 



Also helps you write the application logic, 
helps you separate UI code from functional code, 
helps you connect UI items to functions. 

AppMaker makes it faster and easier to make 
a Mac application. Just point and click to declare 
your data structures, and to design your u.ser 
interface. AppMaker generates resources and 
source code to implement your design. 


Application Logic 

ReadFile() 

GetReniinders {) 
->AddIteiii (nowltom) 

SetMessage {_.) 

GetYearMonthDay() 

SetHourMinute(~) 


AppMaker generates Get and Set functions to 
access your data items and generates code to call 
the Get and Set functions when UI items are 
changed, and to update UI items when data items 
are changed. Also generates file I/O code. 

B*0*W*E-R*S 

Development 


Users describe the AppMaker-generated code as 
“human professional quality.” AppMaker generates 
C, C++, or Pascal for Apple’s Appearance Manager 
and C++ for CodeWairior’s PowerPlant. 

AppMaker is }\ist .$199 from Developer Depot 
(www.devdepot.com) or from Bowers Development 


P.O. Box 929, Grantham, NH 03753 • (603) 863-0945 • FAX 863-3857 
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// Declare a string and initialize it 

Str255 theString =* "\pHello, World!”; 

// Api^end another string, obtained from a S'l'R# resource 
Str255 appendString; 

::GetlndString(appendString, 128, 1); 

// Insure we don’t overrun our boundaries 
SIntl6 charsToCopy = appendString[0]: 

Size theStringSize ” sizeof(theString); 

if ((theString[0] + charsToCopy) > (theStringSize - 1)) I 

charsToCopy = theStringSize - 1 - theString[0]; 

) 

//Append the siring 

; ;BiockMoveData((Ptr)6iappendString[l], theString + 
theString[0] f 1, charsToCopy); 

// Reset the length byte 
theString[0] charsToCopy; 

// Draw the siring 
;:Drawstring(theString); 

Listing 1 demonstrates a typical set of actions that one might 
perform on a string. All of that work and code just to 
concatenate two strings. Listing 2 shows the same code but 
written using LString. Don’t worry if you do not understand 
everything that is going on in Listing 2 because I’ll cover it all in 
coming sections. 

Listing 2; Use of LStr255 __ 

Obtain and concatenate two strings 

// Declare a string and initialize it 

LStr255 theString( 'ApHello World" ); 

// Append another string, obtained from a STR# resource 
LStr255 appendString(128. 1); 

theString += appendString; 

// Draw the string 
::Drawstring(theString); 

As you can see comparing Listing 2 to Listing 1, the same 
result is accomplished but Listing 2 contains a lot less code and 
is much easier to read. 'Fhis just scratches the surface of what 
LString can do. 

Two usage notes. First, when you arc using LStr255 objects 
and viewing them in a debugger, you will actually see two 
instances of your string data within the LStr255 object. One of 
these will be from mStringPtr and the other from mString. Why 
do you see two strings and why are they always in sync? Why 
not just have one siring? Remember that mStringPtr is just a 
pointer to your actual storage for your string, mString; rather, 
mStringRr points to mString. This is how things are designed and 
it’s all OK, don’t worry about it. However if they are not in sync, 
you might want to investigate as this could lie signaling a 
problem. Second, beginning with the next section and 
continuing for the remainder of the article, I will be using 
LStr255 objects in all code listings because LStr255 is the most 
commonly used type of LString. Do remember that what applies 
in lluxse listings will generally apply to other LString derivatives 
as well, like TString and LStringRef. 


TStiing 

I’String is a templatized version of li>tring. It allows you to 
utilize the power and functionality of LString upon any Pascal-style 
string type (Str255, Str63, Str15, etc.). Use of the class is exactly like 
using LStr255, except tliat you instantiate your object through 
normal C++ template instantiation mechanisms. listing 3 fs a rewrite 
of listing 1 using TString. Note as well its similarity to Listing 2. 

Listing 3: Use of TString__ 

Obtain and concatenate two strings 

// Declare a siring and initialize it 

TString<Str63> theString(‘'\pHello World”); 

//Append another string, obtained from a STR# resource 
TString<Str255> appendString(128,1); 

theString += appendString; 

// Draw the string 
::Drawstring(theString); 


LStringRef 

LStringRef is a newcomer to the LString family (it was 
introduced in PowerPlant vl.9.1, post CodeWarrior Pro 3). 
LStringRef provides you with a means to obtain the functionality 
of LString and use it to manipulate a string that you do not have 
ownership of. Unlike LStr255 and TString, LStringRef does not 
contain storage for the string itself; mStringPtr points to a string 
allocated elsewhere. For example, this can be used to change a 
string that is part of some data stmeture. Listing 4 demonstrates 
the use of LStringRef to change the filename in an FSSpec from 
whatever it originally was to “Hello File! copy”. 

Listin g 4; Use o f LStrin^ef_ 

// Obtain our file spec 

FSSpec theFileSpec: 

thcLFile->GGtSpecifier(theFileSpec); 

// Create the LStringRef and have it point to the filename 
LStringRef fileName(sizeof(theFileSpec.name), 
theFileSpec.name); 

// Change the filename entircl)' 
fileName = "Hello File!"; 

//Actually it’s a copy 
fileName += “ copy"; 


Basic Features 

Now that you’ve been introduced to the LString family and 
seen a little of what LString can do, it’s now lime to dig through 
the lines of code in LString.cp and LString.h to really sec all that 
LString has to offer. Ry the way, do make sure you also read 
through LString.h as many of LString’s functions are declared 
inline in the header file. 

Object Construction 

If you look through the LString sources, you’ll notice that 
there is only one LString constructor. That’s all that LString needs 
as it performs the core setup of the class’s functionality. Where 


46 


The Ultra-Groovy LString Class 


MacTech • January 1999 












the constnictors are really needed is witliin the subclasses. Look 
at the number of constructors there are for LStr255! And look 
wiiat you can do with all of those constnictors as well. You can 
create your LStr255 from: another LStr255, another LStrIng, a 
Pascal-style string, a C-style string, an arbitrary string of text, a 
single character, data within a Handle, from a ‘SIR ‘ or ‘SIR#’ 
resource, from a long or short integer, a FourCharCode, and from 
floating point values (long double). Wow! That covers just about 
every and any way you might want to create your LStr255 object. 

If you look at the implementation of most of those LStr255 
constnictors, you’ll see many of them call the Asslgn() method. 
AssignO assigns tlie given value to the LString object. Just as the 
constructors use Assign(), you are free to use Assign() as well 
when you wish to assign a value to your LString object. 
Furthermore, as a logical use of C++, you can see in LString.h 
tliat the assignment operator (operator =) has been overloaded 
with just as many combinations for those of you that prefer the 
use of operators in logical situations. Listing 5 demonstrates the 
many ways Assign() can be used. 

Listing 5: The Many Faces of AssignO 

Each line group produces the same result of creating an LStr255 object and giving it a 
string of “Hello,Assign!\ 

// Create and assign by initialization 

LSt255 initString("Hello, Assign!"); 

// Create and assign by A.ssignO 

LStr255 asslgnString; 

assignstring.Assign(’‘\pHcllo. Assign 1"); 

// Ocaie and assign by assignment 

LStr255 assignmentstring = assignString; 

String Manipulation 

Now that you have created your LString and given it some 
text, you will probably want to do something with the text in 
that string. Ibis functionality is what LString tends to be used for 
most, and within this subset lies the use of Append(). 

AppendO appends a given value to an LString object. What 
can be appended is again just about anything (.see LString.h for 
a complete list). As with AssignO ^ind operator =, so with Append() 
and operator +=. You’ll probably find yourself using operator += a 
great deal as it’s so simple to type and makes your code so much 
easier to read. One issue to note witli operator += (and perhaps 
other overloaded functions in LString) is that depending what 
you are trying to append you may receive compiler errors about 
an ambiguous access to an overloaded function. For instance, 
the following line of code will generate this error because the 
compiler cannot determine if you intend 1 to be treated as char, 
unsigned char, long, or short: 

theString +* 1; 

If you receive tliis compiler error, all you need to do to resolve 
it is apply a static_cast (or C-style cast) which will tell the 
compiler explicitly how you wish the value to be treated: 

theString static_cast<SInt32>(l); 


"IN JUST A FEW SECONDS I'VE SUCCESSFUULY TRACKED 
DOWN A MEMORY CORRUPTION BUG THAT HAS BEEN ELUD¬ 
ING ME FOR ABOUT 3 MONTHS. FANTASTIC 

-Bryan Christianson- 


5F0TLIQnT 


The #1 Macintosh bug detection tool! 


• Detect memory leaks automatically 
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• Faster than ever before 

FREE 
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941.795.7801 Fax: 941.795.5901 
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In addition to member functions for appending, LString also 
provides some global string addition operators (operator +). They 
are not LString memlxT operators, but do act upon LString 
objects. These operators concatenate LString objects with: 
another LString object, a pointer to a string, or a character. The 
result of the addition is an LStr255 object. You can find these 
operators declared about mid-way through LString.h and defined 
near the bottom of LString.cp. 

Finally, what would string manipulation l>e if you could not 
compare .strings! You will find in LString.h a boat-load of global 
comparison operators that let you do just about any sort of string 
comparison you can think of: equals (operator ==), not equals 
(operator !=), greater than (operator >), less than (operator <), 
greater than or equals (operator >=), and less than or ecjuals 
(operator <=). Listing 6 demonstrates the many ways you can 
manipulate strings with LString. 

Listing 6: String Manipulation_ 

// Create our string. “Hi" 

LStr25') theString(“Hi"); 

//Wlioops! We forgot the punctuation 

theString += ‘; 

// Ocatc a new siring from 2 smaller strings 

T.Str255 newString; 

newString = theString + ‘*\p My name is John.”; 

// Is our newString the same a.s our old .string? 
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// If so, beep. 

if ( newString = theString ) ( 
::SysBeep(2); 

) 


Utilities 

Rounding out the basic features of LString are some utility 
functions. They fall into two groups: object-related and public. 

The object-related utilities are utilities that are class member 
functions and only behave in relation to their associated LString 
object. These are methods like: Length(), which returns the string 
length as an Ulnt8; ShortLength() which returns length as an 
Slnt16; LongLengthO which returns length as an Slnt32 (the 
different return types are to ease places where you need the 
string length but do not wish to typecast to match a function 
parameter or avoid an implicit arithmetic conversion); 
GetMaxLengthO, to return the maximum length the string can be; 
TextPtrO and ConstTextPtr() to return a Rr (or const Ptr) to the raw 
text (avoids those ugly (Rr)&theString[1] situations, as was used 
in Listing 1); operator Q to allow access to individual characters 
in the string, just like you could with a basic array. Listing 7a 
illustrates the use of these utilities. 

Listing 7a; Utilities _ 

LStr255 theLStr255("\pYea"); 

'rSlring<Slr2S5> thcTStr255; // LString::I.StringO properly 

// initializes to null. 

// Manually copy the text out of the LSlr255 into a Str255 

::RlockMoveData(theLStr255.ConstTextPtr(), 

(Ptr)&theTStr255[n, 
theLStr255.LongLength() ); 

// Reset length byte 

thGTStr255[0] - theLStr253.Length(); 

'llie public utilities of LString are a small group of static 
methods, publicly available for calling by pretty much anyone 
anywhere in your program (within reason, of course). These 
methods handle the most common string manipulations like: 
CopyPStrO, to copy one Pascal-style string into anotlier Pascal- 
style string (e.g. Str255 to Str255); AppendPStr(), for a static version 
of LString::Append(); CStringLength() for obtaining the length of a 
C-style string with an upper limit of 255; FourCharCodeToPStr() 
and PStrToFourCharCodeO for converting a FourCharCode (y’know, 
TEXT, ‘PICT, ‘PPob’) to a Pascal-style string and back again; and 
FetchFloatFormatO and StringToLongDouble() to aid in some cjuick 
floating-point conversions. Listing 7b presents a display of these 
utilities’ features. 

Listing 7b: Static Utilities _ 

// Create a Pascal-siylc string and assign it a value 

Str235 herString; 

LString:iCopyPStr(“\pMary". herString); 

//Tlirn it into our app’s signature 

FourCharCode herSig: 

LString:iPStrToFourCharCode(herString, herSlg); 


// Clear original storage 
herString[0] “ 0; 

//And back again 

LString::FourCharCodGToPStr(herSig, herString); 
//Add the rest 

LString::AppendPStr(herString, “\p Victoria”); 


Power Features 

In addition to the basic functionality’s discussed above, 
LString has some features for tlie power-user that help to round 
out the practicality of the class. If you consider yourself a 
beginner to LString, you should still give these power-features a 
look over as using these power-features is not difficult, and you 
can be a power-user in no time. The substring manipulations 
you may or may not use every day, but the “typecasting” abilities 
you’ll find indispensable. 

LString’s ability to manipulate substrings provides you with 
the capability to perform substring searches, copies, and 
changes to that substring. In fact, you might even be able to 
create your own Find dialog using these features. The search 
functionality in LString allows you to: Find(), locate where a 
substring starts within the string; ReverseFind(), locate the 
position of a substring starting from the end of the string; to see 
if a string BeginsWith() or EndsWith() a specified string; find 
where the string starts within another string either from the 
beginning, FindWithin() or from the end, ReverseFindWithin(). In 
performing these searches, a comparison of text must of course 
be done. LString::ToolboxCompareText() is provided as the default 
mechanism for comparing the text; it uses the Toolbox 
CompareTextO routine. If you do not wish to use the default 
comparison mechanism, you can specify your own CompareFunc 
via SetCompareFuncO to change it to whatever you would like. 
Of course after you have found your substring, you might want 
to do something with it. If you would like you can InsertQ a 
string into your LString object, Remove() a substring from your 
object, or Replace() one substring with another. Or if you would 
just like to make a copy, operator () has l'>een overloaded to 
provide you with an easy way to perform tliis copy. Listing 8 
illustrates LString’s substring manipulation features. 

Listing 8: Substring Manipulation 

// Create the base string 

LStr255 theString ("Get. up. Stand up for your rights."); 

// Ensure the compare function is what we need 

theString.SetCompareFunc(LString::TooiboxCorapareText); 

// Find a target string 

StringPtrtargetString = “\pStand up"; 

UIntS targetLength = targetString(0] ; 

UIntS index = theString.Find( (Ptr)6ttargetString[lJ. 

targetLength ); 

// Make a copy of the urget string 

LStr255 targetCopy(theString(index.targetLength)); 

targetCopy “\p. 

// Insert the copy into the base string 

theString += char_Space; 

theString.Insert( targetCopy, index ); 
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WJiai I itiink is one of the niftiest features of LString is, as I 
like to call them, the typecasting operators. These are a series of 
operator overloads that fake the appearance of a typecast to allow 
your LString object to be flexibly used in many situations. You can 
find the operators listed near the top of the LString declaration in 
LString.h. 'I'hese operators include: StringPtr, ConstStringPtr, Slnt32, 
double, long double, and FourCharCode. When one of these 
operators is applied to the LString object, it converts the string into 
the “requested type” and returns the conversion. Ihat is, apply 
operator Slnt32 and the string is converted to a long integer and 
that long integer returned. The way to apply these operators is just 
like a typecast, but it’s not really a typecast; it’s technically an 
application of that operator, but the implementation and 
application of that operator simulates a typecast for ease of use 
and improved code readability. Fuithermore, when attempting to 
resolve types, the compiler can implicitly apply these operators to 
the LString object for you. Look back at Figure 2 and notice that 
we passed our LStr255 object directly to DrawString? Listing 9 
should clarify how all of this works. 

Listing 9: Typecasting Operators 

// Ocate our .string (FIXEDDECIMAL comes from fp.h) 

LStr255 t.heString(3.lA, FIXEDDECIMAL, 2); 

// Convert it and do some math (the static_ca.st technically 
// isn’t necessary, but here for illustration. Note that it 
// looks like a typecast, but if you watch the code execute 
// you’ll step into operator doublcQ. 

double number =" static_cast<doubie>(theString): 
number *= 2; 

// Convert back to a string. Note there is no operator = 

// for floating point variables.Iliis is becau.se of the 
// need for extra information. 
theString.Assign(riuiiiber. FIXEDDECIMAL,2); 

// Draw onscreen. Note the implicit operator call to 
// operator Stringl^tr. 

::DrawString(theString); 

PowcrPlant uses tliis technique of typecasting operators 
throughout the framework as a handy way to allow your objects 
to be treated as more basic Toolbox types for increased flexil)ility 
and seemlessness between PowerPlant, the Toolbox, and your 
code. See the use of operator Handle and operator Ptr in 
UMemoryMgr classes for another .set of examples. Also, if you 
have access to the Scott Meyers book More Effective 6'++, read 
Item 5: Be wary of user-defined conversion functions, Scott labels 
the above technique implicit type conversion operators and points 
out the various strengths and weaknesses of the alx)ve technique. 

Is Therf a Downside? 

As great as LString is, there are certainly a few downsides. 
There may be others, but these are the big ones in my book. 
First, if you don’t like Pascal-style strings or perhaps they’re not 
as useful as a C-style string would be in a given situation, then 
of course LString would fall under the same roof. But if you use 
and/or like Pascal-style strings then this isn’t much of an issue. 
Second, this code is C++. If you need Pascal-style string helper 


functions in C or another language then LString will not be of 
much use to you. Third, LString’s are C++ objects. As an object 
it will have some additional overhead and memory 
requirements, at least compared to plain amiys (e.g. LStr255 vs. 
Str255). Fuithermore becau.se LString’s are objects you cannot 
place them inside TArray’s, except, as with all objects and TArray, 
as pointers to the object allocated via new. Due to this extra 
work, it’s probably easier to just store plain Str255’s in a TArray 
instead. But do not fret! If you must use Str255’s you can still 
gain the features and power of LString via the LStringRef class 
applied to your Str255’s. 

Give It A Try 

If you haven’t already, give LString a try. 'Lhe code listings 
should all function as compilaiile snippets. And since LString is 
mostly independent of the rest of Pow^erPlant (you may need to 
add the PP_Constants.cp file to your project as well), you can 
easily drop LString.cp into a basic Toolliox or console stationery 
and give them a try. Step through each listing in the debugger 
(make sure inlining is set to “Don’t inline”) and watch how 
things work. Watch where you go, how that pertains to the 
section material being discussed, and how they all fit into the 
larger picture. Just play around and experiment. 

I hope that I’ve been able to give you a good intioduction to 
the LString class and it’s family of subclasses and utilities. It provides 
the Mac OS software developer with a fairly simple yet ptwerflil 
class for worldng with Pascal-style strings. With the ability to create 
strings from almost any source, manipulate tlie contents of that 
string, and conveit it for use in just about any situation, LString is a 
tool worth having in your progr^immer’s toolbox. 

I hope you find LString to be as ultra-groovy as I find it to 
be. But just in case. I’ll borrow one from Dennis Miller: “(Tf 
course that’s just me. I could be wrong.” 
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by Steve Sisak <sgs@codewell.com> 


C++ Exceptions in Mac OS Code 


Modern C++ offers many powerful 
features that make code more reusable and 
reliable. Unfortunately, due to its UNIX 
roots, these often conflict with equally 
important features of commercial quality 
Mac OS code, like toolbox callbacks, 
multi-threading and asynchronous I/O. 
C++ Exception Handling is definitely an 
example of this. In this article, we will 
describe some techniques for using C++ 
Exceptions in commercial quality MacOS 
C++ code, including issues related to 
toolbox callbacks, library boundaries, 
AppleEvents, and multi-threading. 

What are Exceptions? 

Exception Handling isa formal 
mechanism for repotting and handling 
errors which separates the error handling 
code from the normal execution path. If 
you are unfamiliar with how C++ 
exceptions work, you may want to check 
out Chapter 14 of “The C++ Programming 
Language’' by Bjarne Stroustmp or any of 
the other excellent texts on the topic. 

Why are exceptions necessary? 
“Exceptions cannot be ignored” 

— Scott Meyers 

One of the problems in designing 
reusable code is deciding how to 
communicate an error that occurs deep 
within a library function back to someone 
who can handle it. There are several 
conventional ways for library code to 
report an error, including: 


• Terminating the program 

• Returning an error result 

• Setting a global error flag 

• Calling an error function 

• Performing a non-local goto (i.e. longjmp) 

While terminating a program as the result of an error in input 
may be considered acceptable in the UNIX world, it is generally 
not a good idea in software you plan to ship to human users. 

Returning an error or setting a flag are somewhat better, but 
suffer from the fact that error returns can be (and often are) 
ignored, either because the programmer was lazy or because a 
function that returns an error is called by another which has no 
way to report it. Both of these methods are also limited in the 
amount of information they can return. Return values must be 
meticulously passed back up the calling stack and global flags 
are inherently unsafe in a threaded environment because they 
can be modified by an error in a second thread before the first 
thread has had a chance to look at the error. 

Calling an error handler function is reliable, but while the 
function may be able to log the error, it must still resort to one 
of the other mechanisms to handle or recover from the error. 

This leaves non-local goto, which is basically how 
exceptions are implemented — except with formal support from 
the compiler. C++ exceptions extend setjmp/longjmp by 
guaranteeing that local variables In registers are handled properly 
and destaictors for any local objects on the stack are called as 
the stack unwinds. 

Because an exception is an object, it is possible for a library 
developer to return far more information than just an error code. 

What’s wrong with C++ exceptions? 

In a nutshell: Lack of Standardization. 

Like many aspects of C and C++, the implementation of 
exceptions has been left as an implementation detail to be 
defined by compiler vendors as they see fit. As a result, it is never 
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safe to throw a C++ exception from a library that might be used 
by code compiled with a different compiler (or a different 
version of tlie same compiler, or even the same version of a 
compiler with different compile options). 

As a re.sult of this: 

• Exceptions must not be thrown out of a library. 

• Exceptions mtisi not be thrown out of a toolbox callback. 

• Exceptions must not be thrown out of a thread. 

Each of these cases can fail in subtly different ways: 

In the first case, there is no guarantee that both compilers 
use compatible representations for exceptions. The C++ 
standard does not define a format for exceptions that is 
supported across multiple compilers—C++ exceptions are 
objects and there is no standard representation for C++ objects 
that is enforced across compilers. This is also why it’s not 
feasible to export C++ classes from a shared library. 

IBM’s System Object Model (SOM), used in OpenDoc and 
Apple’s Contextual Menu Manager, solves this problem for 
objects quite robustly (even to the extent that it is possible to 
mix objects and classes implemented in different languages like 
C++ and Smairialk), however, there are still additional issues 
which would require a ““System Exception Model” “as well. 


As a platform vendor, Apple could have saved us a lot of 
work here by specifying a “System Exception Model” tliat all 
compiler vendors would agree to implement. In fact they began 
to implement an Exceptions Manager as part of the PowerPC 
ABl but it was left unfinished the last time the developer t(X)ls 
group was killed and Metrowerks took over as the dominant 
development environment’—^so we’re stuck with the current 
state of incompatibility. Hopeftilly, now that Apple is working 
on developer tools again, we might finally see a standard. 

Also, many Mac OS routines allow the programmer to 
specify callback routines which will be called by the toolbox 
during lengthy operations or to give the [)rogrammer more 
control than could be encoded in routine parameters. 
Unfortunately, because of the above limitations, it is not possible 
to throw an error from a callback and catch it in the code that 
called tlie original Toolbox routine. 

This is because there is no way for the toolbox to clean up 
resources that may have been allocated before calling your 
function. In this case it is necessary to save oflF the exception 
data (if possible), return an error to the toolbox, and then re¬ 
throw the exception when the tcx^lbox returns to our code. Of 
course, C++ provides no safe way to save off the exception 
currently being thrown for this purpose and RTTI does not 
provide enough access to extract all data from an object of 
unknown type, so again, we must roll our own. 
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There are a few toolbox managers that provide for error 
callback function that are not required to return. While you 
should l>e able to throw an exception from these callbacks, tliere 
are issues that you should lx? aware of. Specifically, some 
compilers implement so-called “”zer(>overhcad “exceptions” 
which use elal^)rate schemes of tables and tracing up the stack 
to restore program state without needing to explicitly save state 
at the l:>eginning of a try block. Often tliis code gels confused by 
having stack frames in the calling sequence that the compiler did 
not generate, causing it to call terminateO on your behalf. 
(CodeWarrior’s exceptions code also does this if you try to step 
over a throw from Jasik’s Debugger—you can work around this 
by installing an empty terminate(3 handler.) 

C and C++ have no notion of tlireading or acciommodation for 
it. For instance, the C++ standard allows you to install a handler to 
l^e called if an exception is thrown and would not caught, 
however you can only install one such handler per application. 
Further, it is technically illegal for this routine to return to its caller. 
So, there is no ea.sy way to insure that an uncaught C++ exception 
will terminate only tlie thread it was tlirown from rather than the 
entire prognim. (It is possible with globals and cu.stom thread 
switching n)utines, but trick)' to implement — 1 hope to have an 
example in the sample ccxle by the time this is published) 

Intenictions l:>etween threads and the Rintime can also rear up 
and l)ite developers in even more interesting and subtle ways: For 
instance, in earlier versions of CodeWarrior’s nintime, the exception 
handler stack was kept in a linked list, the head of whic'h was in a 
global variable. As a result, if exceptions were mixed with threads 
and the programmer did not add ccxle to explicitly nxmage this 
compiler-generated global, the excei)lion stacks of multiple threads 
would Ix^come intermingled, resulting in Really Bad Tliings^'^ 
hap|x*ning if anyone actually threw an exception. 

What we need is a standard way to package an exception 
so it can be passed across any of these boundaries and handled 
or re-thrown without losing information. 

How did AppleEvents get in here? 

As any Real Programmers’^ knows, gcxxl Macintexsh 
programs should be scrifXable (so u.sers can do stuff the 
programmer didn’t think of), and recordable (so that users don’t 
have to have intimate knowledge of AppleScript to reccxd some 
actions, clean up the result and save it off for future use). 

You may also know that if you want to write a scriplable 
and recordable application and you’re starting from scratch, the 
easiest way to do it is to write a “factored” application — where 
the application is split into user interface and a .server which 
communicate with AppleEvents. 

In a pa.st life I’ve written abcxit how using AppleEvents is a 
convenient way to make your a[)plicalion multi-threaded by 
using an AppleEvent to pass data from the user interface to a 
server thread. [MacTech Dec *94) 

What you may not know (tlianks to the fact that it’s relatively 
hidden in the AppleScript release notes, rather than in Inside 
Macintosh or a Tech NcXe) is that AppleScript provides a relatively 
robust emx reporting mechanism in the form of a set of optional 


parameters in the reply of an Ap[)leEvent which can specify, 
among other things, the error ccxle, an explanatory string, the 
(AEOM) object that caused the error, and a bunch of other stuff. 

Further, you may know that the AppleEvent manager 
provides a data stnicture that can hold an arbitrary collection of 
data (AERecord). 

Putting this all together, if we define a C++ exception class 
which can export itself to an AERecord, we can both return 
extremely explicit error information a user of AppleScript (or 
any OSA language) and provide a standard format for exporting 
exception data across a libraiy boundary. Also, since an 
AERecord can contain an arbitrary amount of data in any 
format, the programmer is free to include any information he 
wants in the exception — anything the recipient doesn’t 
understand will be ignored. 

Implementation Details 

Following are some excerpts from an exception class and 
support code which do ju.st this. Full source for a simple 
program using this code is provided on the conference CD. The 
exception mechanism is actually implemented as a pair of 
classes: Exception and IxxationlnCode and a series of macros 
which provide a reasonably efficient mechanism for reporting 
exactly where an error occurred and returning this information 
in the reply to an AppleEvent. 

Using this mechanism, it is not only po.ssible to throw an 
error across libraiy boundaries, but also between proce.sses or 
even machines. 

Detection and Tlirowing Errors 

The implementation of the Exception classes is divided 
between two .source files: Exception.cp and LocationlnCode.cp. 
The class Exception is the abstract repre.sentation of an 
exception. It has 2 sulxia.s.ses: StdException and SilentException. 

If you look at the.se two files, you’ll notice that most of the 
functions that are involved in failure handling are implemented 
as macros in Exception.h which evaluate to methods of anotlier 
cla.ss, LocationInCode — for instance, FailOSErrO is 
implemented as: 

//define FailOSErr GetT.oc.it lonTnCodcO .FailOSErr 

//define GclLocaLionlnCodeO LocationlnCode(_LINE_, _FILE_) 

class LocationInCode 
{ 

LocationInCode(long line, const char* file) ... 
void Throw(OSStatus err): 
inline void FailOSErr (OSF.rr err) const 
I 

If (err noErr) 

( // CW Seems not to be- sign extending w/o cast 

Throw((OSStatus) err): 

I 

1 

} 

So that the expression: 

FailOSErr(MyFuncO): 
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Evaluates to: 

LocationInCode(_LINE_. _FTT.F._) .FailOSErr (MyFuncO): 

While this seems needlessly complex, there is a good 
reason for it, involving tradeoffs Ix^tween speed, cxxle size, and 
some “features” of the C++ specification. 

Specifically, the obvious way to implement FailOSErrO is: 

//define FailOSErr (err) if (err) TtirowCerr) 

The problem here is that the macro FailOSErrt) evaluates its 
argument twice. This means that, in the case of an error, 
MyFuncO will be called twice — clearly not what we want. 

Here is one place that C++ can help us out — we can 
implement FailOSErrO as an inline function: 

inline void FailOSErr(err) 

{ 

if (err !“ noErr) 

I 

Throw(err. _ LINE__FILE_): 

1 

1 


Since C++ inline functions are guaranteed to evaluate their 
arguments exactly once, this solves our problem. Further, it 
makes it possible to have overloaded versions of FailOSErr 
which take different arguments, for instance a string to pass to 
the user, so you can write: 

FailOSErr(MyFuncO, “Some Error message”) 

The [problem is that, once you implement this and try to 
access the file and line information, you will discover that, thanks 

to the way_FILE_and_LINE_are defined to work, all errors 

are reported as occurring in Exception.h — which is clearly less 
tlian useful. You would think that. In their infinite wisdom, the 
C++ standards committee would have updated the way that these 
macros work or provided a more robust mechanism for rc[)orting 
the location of an error in code, but they didn’t. 

'Ihe solution presented here is a compromise—by 
instantiating the LocationInCode class from a macro, we insure 

tliat_FILE_and_LINE_evaltiate to a useful location in the 

user’s code, rather than In the exceptions library. Also, by using 
a class, we can reduce code size by allowing the methods of 
TLocationInCode to call each other without losing the actual 
location of the error. 

An added benefit of this approach is that, in the future, we 
could replace the implementation of L(x:aiionInCode with one 
using MacsBug symbc^ls or traceback tables in the code instead 
of relying upon the compiler macros. 

Also, note that FailOSErrO and the constructor for 
LocationInCode are declared inline to maximize speed, but then 
call an out-of-line function (Throw) to minimize code size in the 
failure case. 

Adding Information 

At any point in handling an error you can add information 
to an Exception by calling Exception::PutErrorParamPtr or 


Exception::PutEiTorParamDesc. For instance, if you were in an 
AppleEvent handler and wanted to set the offending object 
displayed to the user, you could write: 

try 

I 

// wtialcvcr 
) 

catch (Exception^ exc) 

( 

exc.FuLErrorParamDescdcAEOffGndingObject. whatever, false); 
throw: 

1 


Ihese routines also take a j)arameter to tell whether to 
overwrite data already in the record — this is useful to ensure 
that the first error that occurred is the one reported to tlie user. 

Insuring Errors are Cauglit 

Because it”s not safe to throw C++ exceptions across a 
library boundary, we need a mechanism to insure that all errors 
are trapped and properly reported. Unfoitunately, unlike Object 
Pascal, we can’t just call CatchFailuresO to set up a handler — 
the code which might fail must be called from within a try block. 

Also, because C++ effectively requires catch bloc'ks to 
switch off of the class of the object thrown, and doesn’t sup[X>rt 
the concept of finally’ like Java, this master exception handler 
can end up containing cjuite a lot of duplicated code. 
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In order to minimize code size, the static method 
Exception: :vStandardizeExceptionsO provides a way to have a 
function called from within a block that will catch all errors and 
convert them to a sulxlass of Exception. If you plan to support 
other exception classes, such as tlie ones in the C++ standard 
library, you would modify this function to do the right thing. 

OSStatus Exception::vStandardizeExceptions 
^ (VAProc proc, va_list arg) 

StdException exc(GetLocationInCodeO); 
try //Call the proc 

return (*proc)(arg); 

) 

catch (Exception& err) //Exceptions are OK 

throw /•err*/; 

) 

catch (char* msg) 
exc.PutErrorParamPtr( 

keyErrorString, typeChar. msg. strlen(insg)); 

catch (long num) 

( 

exc.SetStatus(num): 

) 

catch (...) 

{ 

) 

if (LogExceptions0) 

{ 

exc.LogO ; 

} 

exc.AboutToThrowO : 
throw exc: 
return 0: 

) 

There are several other convenience routines, all of which call 
througli Exccpti()n::vStandardizeExceptionsO, wliidi capiure all 
exceptions and convert iliem to an OSErr or write them into an 
AppleEvent. For instance, the following tan be used by an 
ApplcEvcnt handler to catch all errors and return ilicm in the event: 

OSErr Exception::CatchA£Errors(AppleEvent* event. 

VAProc proc. ...) 

I 

va_list arg; va_start(arg. proc); 

OSStatus status; 
try 
f 

status = vStandardizeExceptions(proc, arg); 

catch (Exception& exc) 

1 

status = exc.CetOSErr0; 

if (event && event->dataHandle != nil) 

I 

if (status != errAEEventNolHandled) 

( 

//AppleScript has an undocumented “feature" 

// where if we put an error parameter in an 
// unhandlcd event, it reports an error rather 
// than trying the system handlers. 

GetLocationInCodeO.LogIfErr( 
exc.GetAEParams(*event, false)); 

J 

) 

) 

va_end(arg); 

if (status <“ SHRT_MAX && status >= SHRT_MIN) 


{ 

return (OSErr) status; 

1 

else 

( 

return eGeneralErr; 

) 

) 

This pair of functions reports all errors to the user. (The 
Exceptions library allows the programmer to install a callback to 
report exceptions to the user. Not that here we use 
vStandardizeExceptions to insure lhal all exceptions are 
converted to a subclass of ExceptionO.) 

static OSStatus report_exception(va_list arg) 

VA_ARG(Exception*, exc, arg); 
exc->Report0; 
return 0; 

1 

void Exception::ReportExceptions(VAProc proc, ...) 

va_list arg; va_start(arg, proc); 
try 
I 

GetLocationInCode().FailOSStatus( 
vStandardizeExceptions(proc, arg)); 
va_end(arg); 

} 

catch (Exception& exc) 

{ 

va_end(arg); 
try 

{ 

StandardizeExceptions(report_exception, &exc); 

catch(ExceptionSf excl) 

I 

excl. Log(); // don’t throw errors in reporting 

) 

) 

Conclusion 

Exception handling is both useful and practically required 
in robust code. However, C++ exceptions have a number of 
limitations which you must be aware of when you are 
developing code which uses operating .system features not 
supported by the language. However, using the techniques 
described here, these limitations ’are not insurmountable. 
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JAVATECH 


by Andrew Downs 


Writing an OS Shell in Java 


Building a Facade 


INTRODIKTION 

This article describes the design and 
implementation of a Finder-like shell written 
in Java. Several custom classes (and their 
meth()d.s) arcexamined: these classes 
provide a subset of the Macintosh Finder’s 
funaionality. The example cxxle presents 
some low-level Java programming 
techniques, including tracking mouse 
events, displaying images, and menu and 
folder display and handling. It also disaisses 
several high-level issues, such as 
serialization and JAR files. 

Java provides platform-dependent GUI 
functionality in the Abstract Windowing 
Tookit (AW'F) package, and platfonn- 
independent look and feel in tlie new Java 
Foundation Classes (Swing) API. In order to 
faitlifuUy model the appearance and behavior 
of one specific platfomi on anotlier, it is 
necessary to use a combination of existing 
and aistom Java classes. Certain classes can 
inherit from tlie Java API classes, while 
overriding tlieir appearance and functionality. 
This article presents technicjues used to 
create a Java application (Facade) that 
provides some of tlie Macintosh Finder’s 
capabilities and appearance. As a Java 
application, it c-an theoretically run on any 
platform supporting the Java 1.1 and JFC 
APIs. Figure 1 provides an overview of the 
Facade desktop and iLs functionality. Figure 
2 shows a portion of the underlying object 
model. It contains a mixture of existing Java 


classes (such as Component and Window) and numerous custom 
classes. In the diagram, the user interface cJasses are separated from 
the support classes for clarity. 



Figure 1. Facade on Windows 95. 



Fig^re 2 Facade object model (partial). Only the inheritance 
structure is shown; relational attnhutes are not shown. 
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The Object Modh. 

Facade’s object model utilizes tlic corc Java packages and 
crlasses where possible. However, in order to provide the 
appropriate appearance and speed, custom versions of several 
standard Java classes were added. For instance, the DesktopFrame 
cla.ss is used to display folder contents. Its functionality is similar to 
the java.awt. Frame class. However, additional behavior (i.e. 
window-shade) and ap{>^arance rec|uiremenLs dictated the creation 
of a “knockofP’ class. 

One advantage of using custom classes can be improved 
speed. This holds true for classes inheriting from 
java.awt.Component: such classes do not require the creation of 
platform-specific “peer” objects at runtime. Less baggage results 
in a faster response. For example, the Facade menu display and 
handling classes respond very quickly. 

In the custom classes, most drawing uses primitive 
functions to draw text, fill rectangles, etc. Layout and display 
customization is assisted through the u.se of global constant 
values which typically signify offsets from a particular location 
(as opposed to hardcoded coordinates). 

Seveml of the classes depictcxl in the object mcxlel will be 
discu.s.sed in this article. 

Appearance and Functionaijty 

Facxide relies on .several graj^hical user interface cla.sses in order 
to provide a Finder-like interface. Ibese classes fall into the 
following categories: 

• GUI 

- IJesktop 

- Menus 

- Ic:ons 

- Folders 

• Support 

- Slartup 

- Tiitiing 

- Constants 

Facade provides a sub.sel of the following operatioas: 

- Menu and menu item selection 

- Di.splaying volume/Iblder contents 

- Dragging icons 

- Opening and closing windows 

- Managing the trash 

- Saving the desktop .state at shutdown (exit) 

- Restoring die desktof) state at staitup 

- Launching applicatioas 

- Dialog di.splay 

- Cut/Copy/Paste 

- Cliiinging the ci-irsor 

- Emulating the desktop database 

Several of these operatioas (and die classes which implement 
diem) will be disaissed in the following sections. 


TheDesictop 

Tlie Desktop class is a direct descendant of the java.awt.Window 
class, which provides a container with no predefined border (unlike 
the java.awt. Frame class). 'Ibis approach allows die drawing and 
petsitioning of elements within the De.sktop aiea, without needing to 
hide the platfomi-specific scTolllyais, dde bar, etc. 

However, this approach means that special ctire and fecxling 
is required to make the menubar work properly. In the cuaent 
implementation, menubar (and menu) drawing is done direedy in 
the Desktop class, using values obtained from diose respiective 
classes. In other words, menus don’t draw themselves. Desktop 
does it for them. 

Menu Creation 

llie following ccxle snippet (Li.sting 1), taken from the Desktop 
constniaor, creates the Apple menu, and populates it widi one item. 
Tlie menu is an instance of the Desktoplmage class. Tlie Apple icon 
(ImgApple) was loaded further up in this method. A similar sequence 
creates and populates the File menu. 

listing 1; Desktop constructor 

Dcjiklop constructor 

C'reating menus in the tX-skiop cx)nsiructor. 

// • Desktop constructor 

H - 

Desktop 0 I 
// <snip> 

// Create the menus and tlieir menu items. 

DesktopImageMenu dim; 

Vector vectorMenuItem.*;; 

DesktopMenuItem dmi: 

// ('.alculate die y-coordinate of the menus (eonstant), 
int newY = this.getYO + this.getMenuBarHeightO - 
( this.getMenuBarHeightO / 3 ); 

// (^alciJate the x-coordinate of the menus (variable). 

int newX = this. getX (); 

// (Create the Apple menu, 
dim = new DesktopImageMenu(); 
dim.setlinage( imgApplc.gclImageO ); 
dim.setXt imgApple.gctXl) ); 
dim.setY( imgApple.getYO ): 

// Create menu itcm'Alxiut..." 

dmi = new DesktopMenuItem( Global.menuItemAboutMac ): 
dmi.setEnabied( true ): 

//Add die menu item to the Vector for this particular menu... 

dim.getVectorO.addElement( dmi ); 

// ...then tell the menu to calculate the item position(s). 

// Note that the Desktop’s FontMetric's objext gets used Iktc. 

dim..setTtcmTxications( this.getCraphicsO .getFontMetricsO ): 

//Add the Apple menu to Uk iiKiiubar’s Vector. 

//The menuhar was instantiated further up in this mcth<xl. 

dmb.getVectorO.addElement( dim ); 

// I’or the next mcnu,calctilate its x-c<x)rdinate. 
newX = imgApple. getX (); 
newX += ( 2 * Global .dcfaultMenuliSep ); 

newX += ( ( DcsklopIniageMenu )dmb.getVector().elemGntAt( 0 ) 

). get Image (). getWidth ( this ); // Line wrap. 

DcsktopMenu dm; 

// Create the lile menu... 
dm = new DesktopMenu(); 
dm.setLabel( Global.menuFi1e ); 
dm.setX( newX ); 
dm.setY( newY ); 

// ...and all its menu items. 

dmi " new DesktopMenuItem( Global.menuItemNew ); 
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dmi.setEnabled( true ); 

dm.getVector().addElement( dmi ); 

dmi = new DesktopMenuItem( Global.menuTtemOpen ); 

dmi.seLEnablcd( false ); 

dm. getVector().addElement( dmi ); 

dmi = new DesktopMenuItem{ Global.menuIteraCiose ): 

dmi.setEnabled ( false ); 

dm.getVector().addElement( dmi ); 

//Tdl the menu to calculate the item ix)sition(}>). 

dm. setTtemLocati ons ( this. get.Graphics (). getFontMetrics () ); 
//Add the File menu to the menubar’s Vector, 
dinb.getVector0 .addElement( dm ); 
newX ( 2 * Global. defaultMenullSep ); 
newX += theFontMetrics.stringWidth( dm.getLabelO ); 

// <ctc.> 


Here, the variable dim is an instance of the class 
DesktoplmageMenu. Tliis specialized menu class simply adds an 
instance variable that contains an Image (in this case, the Apple) to 
the DesktopMenu class. Tbs Ix^havior is the same as other menus, 
except that instead of a String it displays its Image. Tlie x and y 
coordinates of this menu are detemiined by tlie same values 
assigned to the image when it was loaded. 

Tliis object contains one menu item, tlie “About” item. Tliat 
item is enabled, and added to the Vector for the menu, lliis Vector 
contains all the menu items for that menu. Tliis approach provides 
an easy way to manage and iterate over tlie menu items. 

Once the Vector has been setup, its contents are given tlieir x- 
y coordinates for drawing and selection purposes through the 
setItemLocationsO methexi. Although this calculation can be done 
when tlie menu is selected, the code mns faster if those numbers 
are calculated and assigned at startup time. 

Finally, the menu is added to the Vector for the menubar. 
The menubar uses a Vector to iterate over its menus, in the same 
way the menus iterate over their menu items. Iriis will become 
apparent when examining the mouse-event handling code for 
the Desktop class. 

Tlie same approach is shown for tlie File menu, except that File 
contains a String instead of an Image, as well as sevenil menu items. 

Menu and Menu Item Selection 

'This class defines some global values that are shared between 
the Display and McxieSelector classes. These values are collected in 
one place to simplify housekeeping and maintenance. We will refer 
to them from the other classes as Global.NOFMAL, Global.sleep, etc. 
This is the Java syntax for referencing sUitic (class) attributes. Note 
\h:A final rneaas the values cannot be changed after tliey are initially 
assigned, so tliese are constants. 
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Figure 3. Menu item selection. 


The code in Listing 2 handles iiiouseDown events in tlie 
menubar. The first two lines reset the instance variables used to trac:k 
tlie currently active menu and menu item. Since the user has pressed 
the mouse, the old values do not apply. Next, the Graphics and 
corresponding FontMetrics objects for the Desktop instance are 
retrieved. They will lx‘ used in drawing and detennining what 
selection the user has made. 

Next, test to see whether the event occured within tlie 
bounding rectangle of the menubar. This line uses the 
java.awt.Component.contains() method. If the x-y coordinates of the 
mouse event are inside tlie menubar, then determine which menu 
(if any) the user selected. 

Determining the menu selection uses tlie menubar’s Vector of 
menus. Iterate over the Vector elements, casting each retrieved 
element to a DesktopMenu object. (Vector.elementAt() returns Object 
instances by default, which won’t work here.) The meiiLi has its own 
bounding rectangle, which is compared to tlie event x-y coordinates. 
In addition, in order to duplicate the Finder, a fixed pixel amount is 
subtracted from the left-side of the bounding rectangle, and added 
to the right-side. Tliis allows the user to select near, but not 
necessarily directly on, the menu name (or image). Notice also in the 
(big and nasty) if c.onditional that the DesktopMenu retrieved from the 
Vector is checked for an Image (tliis handles tlie Apple menu). If it 
has one, the image widtli is used instead of the String width. 

Once the user’s menu selection has been found, it is redrawn 
witli a blue background. Then, tlie menu items belonging to tliat 
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menu are di^wn inside a bounding rectangle (black text on white 
background). The menu item coordinates, and the corresponding 
bounding rectangle ccx)rdinates, were calculated when the menu 
was aeated, saving some CPU cycles here. 


listing 2: mousePressed 


mousePressed 

The mousePressed method liandles menu selections. 

H - 

// • mousePressed 

n - 

public void mousePressed( MouseEvent e ) { 

// New dick means no previous selection, 
this.activeMenu = -1; 
this.activeMenuItern = -1; 

Graphics g = this.getGraphicsO ; 

FontMetrics theFontMetrics = g.getFontMetricsO; 
if ( dmb.contains( e.getXO, e.getYO ) ) { 

// Handle menu selection. 

for ( int i = 0; i < dmb.getVectorO .sizeO ; i-H- ) { 

// Get menu object. 

DesktopMenu d = ( DesktopMenu )dmb.getVector() .elementAt( i ); 

// Determine if we’re inside this menu. 

//This could be done with one or more Rectangles. 

// Note the (buried) conditional operator it accounts 
// for both text and image (e.g. the Apple) menus. 

if ( ( e.getX() >= d.getXO - Global.defaultMenuHSep ) 

&& ( e.getXO <= ( d.getX() + { d.getLabelO = null ? 

( ( DesktopImageMenu )d ).getImageO.getWidth( this ) ; 
theFontMetrics.stringWidth( d.getLabelO ) ) + 

Global.defaultMenuHSep ) ) 

&& ( e.getYO >= this.getYO ) && ( e.getYO <= 
this.getMenuBarHeightO ) ) { 

// Draw menubar highlighting... 

g.setColor( Color.blue ); 

// Save the current Rcaangle surroimding die menu. 

//'Ihis will speed up painting on tiie following line, 

// and when the user leaves this menu. 

activeMenuRect = new Rectangle( d.getXO - 

Global.defaultMenuHSep, this.getYO, ( d.getLabelO = 
null ? ( ( DesktopImageMenu )d ).getlmageO.getWidth( 
this ) : theFontMetrics.stringWidth( d.getLabelO ) ) + 

( 2 * Global.defaultMenuHSep ). getMenuBarHeight() ); 
g.fillRect( activeMenuRect.X. activeMenuRect.y, 
activeMenuRect.width, activeMenuRect.height ); 

// Draw menu String or Image. 

g.setColor( Color.black ); 
if ( d.getLabelO != null ) 

g.drawString( d.getLabelO, d.getXO, d.getYO ); 
else 

g.drawlmage( ( ( DesktopImageMenu )d ).getlmageO, 
d.getXO, d.getYO, this ); 

// Get menu item vector. 

Vector V = d.getVectorO ; 

// If the Trash is full, enable tlie menu item. 

//This code can easily be moved; it is included 
// here for illustration. 

DesktopMenuItem dmi = 

( DesktopMenuItem )v.elementAt( 0 ) ; 
if ( dmi.getLabelO.equals( Global.menuItemEmptyTrash ) ) { 
Desktopimage di = ( ( Desktopimage 
)this.vectorImages.elementAt( 1 ) ); 

String path = di.getPathO; 

File f = new File( path. Global.trashDisplayString ); 
if ( f.exists0 ) ( 

String array [J = f.listO; 

if ( array = null || array.length = 0 ) 
dmi.setEnabled( false ); 
el.se 

dmi.setEnabled( true ); 

} 

1 


// Draw menu background. 

g.setColor( dmb.getBackground() ); 

g.fillRect( d.getltemBounds0.getBoundsO.x, 
d.getltemBounds().getBounds().y, 
d.getItemBoundsO .getBoundsO .width, 
d.getltemBounds().getBounds().height ); 

// Draw menu items. 

for ( int j = 0; j < v.sizeO; j++ ) ( 
g.setColor( Color.black ); 
if ( !( ( DesktopMenuItem )v.elementAt( j ) 

).getEnabled() ) 
g.setColor( Color.lightGray ); 
g.drawstring( ( ( DesktopMenuItem )v.elementAt( j ) 

).getLabelO, ( ( DesktopMenuItem )v.elementAt( j ) 

) .getDrawPointO .x. 

( ( DesktopMenuItem )v.elementAt( j ) 

).getDrawPoint().y ); 

} 

g.setColor( Color.black ); 

// Outline the menu item list boundii^ rectangle. 

g.drawRect( d.getItemBoundsO .getBoundsO - x, 
d.getltemBounds().getBounds().y, 
d.getltemBounds().getBounds().width, 
d.getItemBoundsO .getBoundsO .height ); 

//Add horizontal drop shadow. 

g.fillRect( d.getItemBoundsO .getBoundsO .X + 2, 
d.getltemBounds 0.getBounds().y + 
d.getltemBounds().getBounds().height, 
d.getltemBounds().getBounds().width, 2 ); 

// Add vertical drop shadow. 

g.fillRect( d.getItemBoundsO .getBoundsO .X + 
d.getltemBounds().getBounds().width, 
d.getItemBoundsO .getBoundsO .y + 2, 2, 
d.getltemBounds().getBounds().height ); 

// Set current menu. 

this. act iveMenu = i; 

// Once found, we’re done. 

break; 

} 

] 

) 

) 

The mouseDraggedO metliod (not shown) is responsible for die 
liighlighting and unhilighting of menus and menu items: that is 
where menu items get redrawn with white text on a blue 
background, as depicted in Figure 3. 

Dispiaying Foider &)NTENTS 

Folders in Facade use a combination of core Java classes and 
Swing classes. The container itself descends from java.awt.Window, 
and the paint() method performs the low-level drawing calls 
(drawing the title bar, close box, etc.). The content is displayed 
inside a JScrollPane. 

Once the Macintosh look-and-feel is activated, the scK)llbars 
take the appearance shown in Figuiu 4. The icoas within tlie 
scrollpane are added to a grid layout. This approach works well, 
except that the tendency of tlie scrollpane is to take up the entire 
display area (ignoring the title bar, etc:.). So, on resize of the 
container, tlie scrollpane is also resized. A java.awt.Insets object is 
used to make this as painless as possible: die Insets values are used 
as the buffer area around the scrollpane. 

Like most of the Facade classes, DesktopFolder implements the 
MouseListener and MouseMotionUstener interfaces so it can receive 
mouse events. Within the methods required for diose interfaces, the 
x-y coordinates are checked to detemiine if a close, zcxim, shade, 
grow, or drag operation is taking place, and die container gets 
reshaped appropriately. 
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File Edit Special 



listing 3: addFileTree 

addFileTree 

Building a folder’s display' area. 


// Instantiate the instance variables for this object’s content. 

//The Mac L&F reqniiies botli saoUbai’S. 
pane = new JScrollPaneO ; 
pane.setHorizontalScrollBarPolicy( 
JScrollPane.HORIZONTAL_SCROLLBAR_ALWAYS ); 
pane.setVertlcalScrollBarPolicy( 
JScrollPane.VERTICAL_SCROLLBAR_ALWAYS ); 

// Make sure the argument passed in Is a valid director)^. 

String defaultVolume = s; 
if ( defaultVolume = null ) 
return; 

File theDir = new File( defaultVolume ); 
if ( !theDir.isDirectoryO ) 
return; 

// Retriev’e the contents of this folder/directory, 
contents = theDir.list(); 
int terapLength = 0; 
if ( contents != null ) { 
tempLength = contents.length; 

// Use a Swing panel in.side the Swing scTollpane. 

// Default to a grid layout simply because it looks the best. 

JPanel p = new JPanelO; 

p.setLayout( new GridLayout( 5, 3, 5, 5 ) ): 

// If the contents contain full patli specifications, there will 
// be some extraneous characters that we don’t want to display; 
char pathSeparatorChar = theDir.pathSeparatorChar; 
char separatorChar = theDir.separatorChar; 

Vector V = new Vector(); 

V.addElement( Global.spaceSep ); 
int loc = 0; 
int k = 0; 


H - 

// • addFUcTree 

H - 

public void addFileTree( String s ) { 


for ( int j = 0; j < tempLength; j-H* ) { 
// For each item, separator chars should become spaces for 
// display purposes. 
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File tempFile = new File( theDir, contents[ j 1 ); 
contents[ j ] = 

new StringC conLcnLs[ j ].rcplace( paLhSeparatorChar, ' ' ) 
contents[ j ] = 

new String! contents! j ].replace! separatorChar, ‘ ‘ 
for ! int 1 = 0; 1 < v.size!); i-H- ) ( 

// Parse root volume name. 

// Remove leading ‘%20’ diaratter. 

loc = contents! j ].index0f! ! String )v.elementAt! 1 ) ): 
if ! Toe = 0 ) 

contents! j ] = new String! contents! j ].substring! ! 

! String )v.elementAt! 1 ) }.length!) ) ); 

//Volimic name includes first ‘%20’. 

// Rework lliis for MacOS. 

loc = contents! j ].indexOf! ! String )v.elementAt! 1 ) ); 
// Build the final display String from substrings, 
while ! ! loc > 0 ) && ! loc < contents! j ].length!) + 1 ) ) { 
String si = new String! contents! j ].substring! 0. loc ) ); 
String s2 = new String! contents! j ].substring! loc + ! 

! String )V.elementAt! 1 ) ).length!) ) ); 
contents! j J = new String! si + “ “ + s2 ); 
loc = contents! j J.indexOf! ! String )v.elementAt! 1 ) ): 

} 

} 


// Now build the appropriate icon. 

Image thelmage; 
int tempWidth = 0; 

DesktopFrameltem d; 

Iraagelcon ii = new Imagelcon!); 

// Files obviously kxik different than folders. 

// Set the appropriate Image. 

//This version does not handle mouse clicks on documents, 
if ! tempFile.isFile!) ) ( 
d = new DesktopDoc!); 

ii = new Imagelcon! ! ! DesktopDoc )d ).getImage!) ); 

] 

else { 

d = new DesktopFolder!); 

ii = new Imagelcon! ! ! DesktopFolder )d ).getImage!) ); 
d.addMouseListener! ! DesktopFolder )d ); 

1 

// Set the display Strings, 
d.setLabel! contents[ j 1 ); 
d.setText! contents! j ] ); 

// Set the path for the item. It is built from the paient folder 
// path and filename. 

d.setPath! this.getPath!) + 

System.getProperty! "file.separator” ) + contents! j ] ): 
//And set die icon, 
d.seticon! ii ); 

// Swing methods for positioning the icon and lal-iel. 
d. setHori xontaT AT ignment! JT-abel.CENTER ); 
d.setHorizontalTcxtPosition! JLabel.CENTER ): 
d.setVerticalTextPosition! JLabel.BOTTOM ): 
ii.setIraageObserver! d ); 

//Add die completed item to the panel, 
p.add! d ): 

} 


The Trash 

The trash is simply a directory located at tlie root of the volume 
(for example, c:\Trash). Items can be dragged onto the nash can 
icon, the mouse button released, and the item (and its contents, if it 
is a folder) are moved to tlie trash directory. If the item has an open 
window, that window is destroyed. Emptying is accomplished 
through the “Empty Trash...” menu item in the Special menu. Figure 
4 shows a folder being dragged to tlie trash. Tlie cursor did not get 
capaired in the image, but it is positioned over the trash icon, ready 
to release the folder. 


Special 
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Figure 5. Dragging a folder to the Trash. 


The code in Listing 4 handles the “Empty Trash...” menu item. 
If a match is found between tlie selected item and the constant 
assigned as the Ifash label, the path to the 'Lrash is retrieved. Once 
the code determines the “Trash” is indeed an existing directory, the 
emptyDIrO method is called. Once emptyDir() reairns, tlie icon is 
changed from full to empty. Note that the trash icon is always 
pre.sent in the vectorlmages object. Tliis Vector contains the known 
images (icons) for items on tlie desktoji. The trash is always at 
position 0, the first position, llie root volume is at position 1. lliis 
allows quick, though hardcoded, access to the images when 
repainting occurs, or an image needs swapping. 


Listing 4: handleMenultem 


// Set the panel characteristics, then add it to the scrollpane. 
p.sctVisible! true ); 
pane.getViewport!).add! p. “Center” ); 
pane.setVisible! true ): 

//A coiilaiiier wiiliin a conuiiner wiiliin a container...it works, 
panel = new JPanel!); 
panel. setLayout! new BorderLayoiit!) ); 
panel.add! pane, "Center” ); 
this.add! panel ); 

// Use the Insets objtxt for tliis window to set the viewing 
// size of the panels and scrollpane. 

panel.reshape! this.getinsets!).left. this.getInsets!).top, 
this.getBounds!).width ■ this.getinsets!).right - 
this.getinsets!).left, this.getBounds!).height - 
this.getinsets!).top - this.getinsets f).bottom 
// Ready for display, 
panel.setVisible! true ); 
this.pack!); 
this.validate!); 

] 


liandleMenuItem 

Handling the “limply Trash...” menu item. 

J/ - 

// • handleMenultem 

n - 

public boolean handleMenultem!) { 
boolean returnValue = false: 

// Handle active menu item. 

if ! ! this.activeMenu !=-!)&&! this.activeMenuItem != -1 ) 

) ( 

// Get menu object. 

DesktopMeiiu dm = 

! DesktopMenu )dmb.getVector!).elementAt! this.activeMenu ); 

// Gel menu item. 

String s = ! ! DesktopMenuItem )dm.getVectorO.elementAt! 
this.activeMenuItem ) ).getLabel!); 

// <snip> 

if ! s.equals! Global.menuItemEmptyTrash ) ) { 

//The path to the trash is assumed to be of the form: 
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// <n)ot v()I>/Tra.sh 

DesktopTmage di = 

( ( DesktopTmage )this.vectorIinages.elemeriLAL( 1 ) ); 

String path * di.getPathO ; 

File f = new i*’ile( path. Global.trashDispiayString ): 

// ()ncc wc have llic objcxn that references the Trash dir... 

if ( f. exists0 f.isDirectoryO ) ( 

// Oill the rnetkxl wliich empties it. 

boolean b = this.emptyDir( f ); 

// If successftifcliange the icon back to empty, 
if ( b ) ( 

// Save tlie eurrent boiintLs. We neall>^ want the x-y. 

Rectangle r = 

( ( Desktoplmage )this.vcctorTinages.elementAt( 0 ) 

) .getBoundsO: 

// Change the icon, imgl'rasli iuid img IrasliFiiIl are two 
// instance variables, each referencing die appropriate 
// icon. 

this.vectorIinages.setEleinentAt( this.imgTrash. 0 ); 

( ( Desktoplmage )this.vectorImages.elementAt( 0 ) 

).setBounds( r ); 

// Show the change. 

this.repaint 0: 

) 

) 

] 

) 

) 

Emptying the Trash 

emptyDirO is displayed in Listing 5. Tliis method will empty the 
specified directory recursively. As it finds each item in the directory, 
appropriate action is taken. If the item is a file it is immediately 
deleted. If it is a directory, emptyDir() is called again, with the 
sulxlirectory name as its aigument. Evenaially, all of the files in tlic 


subdirectory arc deleted, and then the sulxlirectory itself Ls removed. 


listing 5: emptyDir 


anplyDir 

Emptying a dirtclor>'. 

H - 

// • emptyDir 

U - 

public boolean emptyDir( File dir ) ( 

// Recursive method to remove a diR-ctory’.s contents, 

// then delete the directory. 

boolean b = false; 

// Ciet the directory contents. 

String array[] = dir.listO; 

// If die |)ath is screwed up, this will c*atch it 
if ( array != null ) I 
// Iterate over die directory conutits... 

for ( int count = 0; count < array.length; count ++ ) { 

String temp = array I count ]; 

// Create a new File object using patli + Iilcname. 

File fl = new File( dir, temp ); 

// Ddcte files immediately. 

// (Jail this metlioti again for subdirectories, 
if ( fl.isFileO ) ( 
b = f 1. delete 0; 

) 

else if ( fl.isDirectoryO ) { 
b = this.emptyDir( fl ); 
b • fl.delete0; 

) 

1 

) 

return b; 

I 



All right, you might not be able to just pack up and head 
straight to the beach. But the crossplatform, 
crossdanguage,, and across-the-network 
compatibility of NeoLogic'^’s embedded object 
database engine will save you so much time, 
you can at least start shopping for sunblock. 

After all, with full binary compatibility across all 
platforms, NeoAccess® lets you create a database on 
one platform, and then simply open it on another, without 
conversion. And, because the API is exactly the same on each 
platform, you can code in the development environment you 
know best and run your application anywhere. 

The result? Users of your product will be able to move around 
freely—across machines, languages, and platforms. Which is 
precisely why companies like Netscape® and NetObjects® 
use our technology, and why you should too. 


' With a paltry memory fingerprint and a lox 
performance advantage over 
competing products, 
NeoAccess lets you use 
system resources in ways 
that make the most sense for 
your application. You can also 
support multiple transactions and users 
with our NeoShare® client/server database 
engine, which— like NeoAccess—is Microsoft 
COM®-compatible. 

Not only that, if you need to use C++ together with 

other interfaces, our NeoOpen® product provides support for 

standards like ODBC. 

Want more information? Run on over to www.neologic.com 
for a closer look. 
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Saving and Restoring State 

Facade uses a variant on the standard Java serialization 
meclianism for saving tlie Desktop state. The ccxle in Listing 6 
illustrates the siiving and restoring of open folder windows. Both of 
tliese methods are in the Desktop class. Note that rather than flatten 
entire DesktopFrame objects, tliis code saves only spec'ific attributes 
from each object, ihe primary reason for tills approach is that it 
avoids any exceptions thrown when attempting to serialize tlie 
Swing components and Images (whic:h are not serializable by 
default) within each DesktopFrame. Anotlier reason is the relative 
ease witli which this approach may l:>e implemented. Plus, it reduces 
the amount of data written to disk. One disadvantage is that the 
current .scroll position of any open window is lost. 

Listing 6: saveState and rcstorcState 


saveState 

Saving and restoring opc*n DfsktopFnuiKS. 

n - 

// • savcSiaic 

H - 

private void saveState() I 
//The Desktop data will be stORxl in a file at the nxH level. 

DesktopImage di = 

( ( Desktoplmage )this.vectorImages.elementAt( I ) ); 

String s = new String( di.getPathO + ”De.sktop.ser" ): 
try \ 

FileOutputStream fos “ new FileOutputStreain( s ); 

ObjectOutpiitStroam outStream = new ObjectOutputStream( fos ); 

// Use a temponiry Vector to hold die o|x.n DeskiopFnimc.s. 

//Tliis should not be necessary when sliiitling down, but it 
// is a good habit to follow. 

Vector v “ new Vector(); 
v = ( Vector )this.vectorWindows.clone(): 

// tJse iinodier temporary Vector to hold die anribuics to save. 

Vector temp ” new VectorO: 

for ( int i = 0; i < v.sizeO; iH ) ( 

// rt>r cadi Dcskloplranie, well save its path, display 
// string, and its bounding Rectangle. If window-sliading is 
// in effect on an object, restore the ftill height before 
//.saving. 

DesktopFrame df = ( DesktopFrame ) v. elementAt ( i ); 
tcmp.addElementf df.getPathO ); 
temp.addElement( df.getLabel() ); 
if ( df .getShadeO ) I 
df .restoreHeightO; 

) 

temp.addElement( df.get Bounds() ); 

1 

//Write the Vector coniaits to the .sct file. 
outStream.writeObject( temp ); 
outStream.flush0; 
outStream.close 0; 

) 

catch ( lOException e ) { 

System.out.printIn( "Couldn’t save state." ); 

System.out.printIn( "s = “ + s ); 
e.priritStackTraceO; 

) 


// • restoreState 

n - 

private void restoreState() ( 

//'llie Desktop data is .stored in a file at the root level. 

// 'Iliis .step occtirs near the end of the Desktop construcior, 

// Jind .so can use the rcxit volume to build the paUi. 

Desktoplmage di = 

( ( Desktoplmage )this.vectorImages.elementAt( I ) ); 


String s = new String( "WDesktop.ser" ): 
try ( 

// Open die Die, and read the contents. In this version 
// we know it’s just one Veaor. 

FileInputStream fis = new FilelnputStream( s ): 

ObjectInputSt ream inStream = new ObjectlnputStreamf fis ); 
Vector v = new VectorO; 

V - ( Vector )inStream.readObject(); 
inStream.close 0; 

Rectangle r = new Rectangle(); 

for ( int i = 0; i < v.sizeO: 1++ ) ( 

// llcralc over the Vector contents. We know the sjivc formal: 

// cadi field corresponds to a specific anribuic of a 
// DesktopFrame. 

// Create a new Dc'sktopFninic using the retrieved path, 
s = ( String )v.elementAt( i ); 

DesktopFrame df = new DesktopFrame( s ); 

// vSei its label lusing the next Vector dement, 
i+f; 

s = ( String )v.elementAt( i ); 
df. setT.abel ( s ); 

// Set its bounding Rcaimgle using die next Vector element. 
i++; 

r = ( Rectangle )v.elementAt( i ); 
df.setBoundsi r ); 

// I^rqxirc and display the DesktopFrame*. 
df .packO ; 
df .validateO: 
df .showO; 
df.toFront0; 
df.repaint 0; 

//Add die object to the Dc*sktop’sVector of opc*n wintkiws. 

Desktop.addWindowf df ); 

) 

1 

catch ( ClassNotFoundException e ) ( 

System.out.printin( "ClassNotFoundException in 
retrieveStateO ." 

); 

) 

catch ( TOException e ) [ 

Syslem.oul.println{ "Couldn’t retrieve state." ); 
SysLem.out.printIn( “s = " + s ); 
e.printStackTraceO ; 

I 

1 


Pa(icaging (Facade in a JAR) 

Facade can lx? run from a Java Archive (JAK) file, or as a set of 
.separate classes plus images. In addition, the Macintash look-and- 
feel classes must be present (usually in a .separate JAR). Tlie system 
environment variables ncc’d to lx? .setup pioperly in order for the 
Java aintime to find the clas.ses. 

The JAR file for Facade was cieated like this: 

jar cf Facade.jar /Facade/*.class /Facade/*.g.if 

Once the environment variables are set. Facade c'lin lx? invoked 
as follows: 

java Facade 


Other Ciasses 

In addition to the java.awt classes alrejidy dlsais.sed, there are 
other packages imd classes used often in Facade. 

This program relies heavily on the java.util.Vector class for 
maintaining a .semblance of order among the various objects. 
Several Vector instances are used for tracking icons and open 
windows. Figure 6 illustrates the core concept of a Vector: it is 
a growablc array. 
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Figure 6. Creating and populating a Vector. The arrow reprasenls 
a pointer to the current eknmmt al the end of the Vector. 

Hie java.io.File class provides most of the file system 
optfrations for display and management. Refer to the references 
[provided in the bibliogiaphy for Aid details. One platfomi-spccific 
detail that was not discussed is the translation of a root path to a 
form that is valid for a File direcloiy object. For example, calling 
the File.listO metliod on the path “c:V’ will not return any file or 
folder names, but calling tlie same methtxl for the path T will 
return the r(X)t directory contenLs. 

Facade afso uses the Java Foundation Classes (Swing) to 
provide a consLstent look and feel acro.ss platforms, primarily 
for window scrolling operations. Swing runs a bit slow right 
now, but as peforrnance improves Swing classes can be 
substituted for some of the Facade custom classes. For 
example, the code that handles folder content display can be 
mexlified to show' a tree structure. This capability should be 
easy to implement using the Swing classes, with little 
additional low-level drawing ccxle. 


Conclusion 

Writing Java classes to model operating system 
functionality requires some choices, particularly in the 
selection of pre-defined GUI classes. Although many classes 
are available, you w'ill need to create others, since performance 
of the pre-defined classes may be slow, or the behavior may 
not be exactly what you need. Roth the a[)pearance and 
behavior for custom GUT elements must be written. 

This article touched on several key areas: desktop layout, 
menu and moUvSe handling, icon display and movement, the 
trash, and saving and re.storing the desktop state. All of these 
functional areas can be modeled eavSily using the Java 1.1 
classes, supplemented by JFC and custom-built classes. 

REFLRLNCliS 

• Developing lava Beans . Robert Englander, O’Reilly & Ass(K:iates, 
Inc., 1997. 

• lava in a Nutshell . David Flanagan, O’Reilly & Assexiates, Inc., 
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• Exploring lava . Patrick Niemeyer and Joshua Peck, O’Reilly & 
Associates, Inc., 1997. 

• Programming with IFC . Scott Weiner and Stephen Asbury, John 
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No Cute 


Panels 


Unlike some high-tech companies, Zocalo 
isn't reaching out to the mass market. 
We've been serving business, industry, 
and higher education exclusively for 
more than a decade. So your business' 
Internet traffic doesn't queue up behind 
sorne kid's game of Doom, and your 
network staff don't have to wait on'hold 
to speak to our technicians. 


ISPs to offer native routing of AppleTalk, 
IPX and DBCnet between customers' 
office IANs throughout the world, at 
spSbds up to 45 megabits per second. 
'We also deliver fully<onfigured 
equipment, proactive customer service, 
on-site maintenance, and a firewall 
custom-built to your specs, all at no extra 
charge. We take responsibility for your 
wide-area network and Internet 
connection right up to the FDDI or 
Ethernet jack in each of your offices. 

If cute just isn't enough for your business, 
call our network engineers and find oy| 
why Zocalo is the first choice for 
industrial-strength business netvyorking. 





hy Jessica Courtney <press_releases@maclech.com> 


VOODOO Server 

UNI SOFTWARE PLUS introduced VOODOO Server, a 
successor of their version control tool VOODOO, which won 
a MacWoiid/MacTech Eddy Award last year. 

VOODOO Seiver is a real client/server solution. This 
forms the basis for a highly efficient and robust multi-user 
environment. Efficient, because all time consuming tasks can 
be delegated to the server and the developer’s machine is no 
longer slowed down (e.g., from the client’s point of view, a 
check-in operation is reduced to the transfer of the file to the 
server). Robust, because the .server application is the only 
process that works on the database. In combination with a 
solid transaction mechanism the client/server architecture 
minimizes the risk of database corruption. Since the server 
application can run either on a server machine anywhere on 
the network but also on the local machine, VOODOO Server 
is scalable from single user projects up to large projects with 
many developers. 

VOODOO Server in combination with the CodeWarrior 
plug-in offers a user-friendly version control solution that 
enables you to manage your software project without having 
to deal with additional complexity and bureaucracy. The 
design goal was to give you access to all necessary 
information and functions without having to learn version 
control vocabulary and remember revision numbers like 
I. 4 . 3 . 5 . 6 . 2 . Instead tlie CodeWarrior plug-in for VOODOO 
Server offers all the functionality and version information 
directly inside the CodeWarrior IDE in an easy-to-use Mac-like 
user interface. 'i‘he package includes a tutorial that lets you 
learn anything you have to know within only a few hours. 

VOODOO Server introduces a new concept called 
“Project Parts” or simply “Parts”. A part represents a subtree 
of a project with all included files and folders. A VOODOO 
project consists of an arbitrary number of parts. Parts can be 
shared among projects. If you make changes to a part from 
one project, these clianges are propagated to all other 
projects sharing this part. 

VOODOO Server keeps track not only of the different 
versions of the files, but also of the folder structures. This 
allows you to reconstruct earlier configurations of your 
project exactly as they appeared at that time, including the 
folder structure. VOODOO Server keeps also track of the 
renaming of files and will even realize if you delete a file 
from the VOODOO project and add the same file again later. 
<http://www.unisoft.co.at/products/voodooserver.html> 
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Fast Mac ISAM Access 
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Real-world data management 
solutions are typically more complex 
when one examines the pieces, 
than initially recognized by the 
majority of database programmers. 

All software projects are complex 
puzzles comprised of many details, 
most of which are dala-related. Often 
kxlay’s “DBMS” solutions sacrifice 
the speed or control essential for a 
competitive application. 

c-trcc Plus% by FairCom, has 
been the choice of commercial 
developers for twenty years precisely 
because it offers the flexibility and 
control at the detail level to fit a 


wide variety of data management 
needs. Proven on large Unix servers 
and workstations, c-tree Plus’s 
small footprint and exceptional 
performance have also made it the 
engine of choice for professional 
developers on Mac and Windows, 
c-tree Plus offers sophisticated 
ISAM level control with which the 
developer may define precise data 
management solutions, making it a 
perfect fit for any development 
project requiring specific data 
handling features. 


C-t:ree Plus® offers the most; 
mat;ure ISAM solution today... 


FairCom's 
c.tree Plus 
database engine: 

• Advanced Indexing Technology 

• Complete Source Code 

• Complete Transaction Processing 

• ODBC Interface from 
Windows clients 

• Over 25 Developer’s 
Servers Included 

• Royalty Free 

• Standalone, Multi-u.ser or 
Client/Server Models 

• Y2K Compliant 

• Supports Metrowerks, 

Symantec Compilers 



The FairCom 
Server: 

A solid, high perfonnance 
database server that is scalable, 
portable and offers unequalled 
control. FairCom has been providing 
database .solutions to the commercial 
development community for twenty 
years and supporting Mac for nearly 
as long. You won’t find a better Mac 
DBMS solution, with these features 
and performance anywhere cl.se! 

• Client Side Source Code 

• File Encryption 

• File Mirroring Logic 

• Full Conditional Index Support 

• Full Heterogeneous Networking 

• Multiple Communication Protocols: 
ADSP; SPX; TCP/IP 

• Online Data Backup 

• Small Memory Footprint 

• Flexible OEM Licensing Options 

• Source Code Availability 


All t:hese platforms 
supported in one package: 

Mac, MIPS ABI, DEC Alpha, Sun SPARC, Windows 9X, 
SCO. 880PEN. AIX, RS/6(XX), HP9(X)0, Sun OS, 
Interactive Unix, Linux (Alpha...), AT&T System V, 
QNX, Free BSD, OS/2, Windows NT, Windows 3.1, 
DOS, Netware NLM, & Banyan VINES. 




DonH; wait, see for yourself! 

USA. 800.234.8180 


Phone: USA 573.445.6833 
JAPAN +81.59.229. 

(Vwr 


11.3872.9802 
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Stocking Your Toolbox 


Ttic Toolbox was one of the early strengths of the 
Macintosh platform. From the beginning, it has armed 
programmers with an assortment of routines to make their job 
easier. Even so, there are those time when you wish tlie 
Toolbox went just a little further, or lielped you out in just 
one more area. This month we are going to look at some 
third-party goodies which fill in the gaps. 

Text 

'lextEdit, the Mac’s built-in text-handling package, is 
great for simple text-handling, but everyone is aware of its 
limitations — the most important one being that it can’t 
handle more than 32K of text. Fortunately for all of us, Marco 
Piovanelli stepped up and create WAvSTF., the WorldScript- 
Aware Styled I ext Engine. It can handle larger stretches of 
text, limited only by available memory, bui its enhancements 
don’t stop there. As its name implies, it is WorldScript savvy; 
it also supports tab stops, drag-and-drop, and embedded 
objects. It comes with an in.structive demo application and 
Inside Macintosh-style documentation, and it is the basis of 
the its author’s Style text editor, which shows off its features 
nicely. The WASTE API is modeled closely after TextEdit 
itself, and accordingly the programmer needs to be familiar 
with the standard Mac text editing routines in order to get the 
most out of WAS'l'E. For those who want a direct comparison, 
the best place to look is in the source code for the SIOUX 
console window, which is part of Metrowerks’ CodeWarrior. 
It has both a 'lextEdit and a WASTE implementation together 
in one file, making it easy to see how they correspond. 

The WASTE Page 
<http://www.boingo.com/waste/> 

Timothy Paustian, author of the CWASTEEdit PowerPlant 
wrapper class for WASTE, has written a text engine of his 
own, the WTTextEngine (or WT++). It is still under 
development, and is entirely C++ based, so it’s handy for 
those who prefer a completely object-oriented alternative. 
The package includes an example application which 


demonstrates adding multiple undo, drag-and-drop, and 
AppleScript support to the engine. 

WTTextEngine 

<http://www.bact,wisc.edu/WTTextEngine/Overview.html > 
CWASTEEdit 

<http://www.bact.wisc.edu/CWASTEEdit/CWasteEdit.html> 

C 01 VTR 01 .S 

1 first ran across Kyle Hammond’s web pages on the trail 
of .something known as the A List. The A List is Kyle’s 
replacement for the 'Toolbox’s List Manager. Unlike the List 
Manager, it supports cut, copy, paste, and drag-and-drop, and 
very large lists (for tho.se hopefully rare occasions where it is 
appropriate to display a huge li.st using this sort of UI 
element). Al.so, since it’s not an LDEF it ends up being much 
faster than the List Manager (which still contains emulated 
(’ode), and it’s more flexible. For in.stance, it supports the u.se 
of callbacks for drawing, highlighting, and disposing of cell 
data, so it is ea.sy to supply your own routines to display lists 
of non-text data. 

Kyle’s site al.so has a few more handy pieces of code to 
help you with your interface. Fir.st there is GetMultiple, a 
function which uses Cu.stomGetFile to allow users to select 
more than one file at a time, with an interface modeled after 
CodeWarrior’s ‘‘Add Multiple...” command. This may be 
partially superceded by Navigation Services, but the usual 
problems of backward compatibility will render it useful for 
a while to come. A second set of functions, 
EditTextCnilExtras, help with the handling of Appearance 
Manager editable text controls, and there are a few other 
interesting things there as well. It’s definitely a site worth 
checking out. (And generously, Kyle has made all of this code 
available for free.) 

Kyle Hammond's Mac Programming Page 
<http://genbiol.cbs.umn.edu/staff/hammond/MacProgramming.html> 
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The Universal PPP API 

It is annoyingly involved to monitor and change the state 
of a PPP connection, because each PPP driver (O'r/PPP, 
FreePPP, etc.) has its own interface to do this. Luckily for us, 
the details have been sweated out for us by Sailmaker 
Software. They have written the Universal PPP API, which 
implements a wrapper around the various PPP interfaces, .so 
you don’t have to worry about which PPP software your user 
is running, even if they change it without restarting your 
application. It is shareware, and is distributed as a binary 
library (callable from C, C++ and Pascal); the source code is 
available for an additional charge. 

The Universal PPP API 

<http://www.sailmaker.co.uk/uppp_api.html> 

MoreFilrs 

The MoreFiles distribution is such an essential collection 
of routines that you have to wonder why it isn’t just rolled 
into the Mac OS itself. MoreFiles is written by Jim Luther, and 
grew out of his experiences working for Apple Developer 
Technical Support. It contains routines for doing just about 
anything you might want to do with files on the Mac, but 
which the OS doesn’t already do for you — things such as 
getting the full path to a file (which you should really really 


avoid doing except for display purposes) or iterating through 
a folder hierarchy. If you need to do something with the file 
system and you don’t know how to do it, look here first. You 
will either see that it has already been done for you, or you’ll 
find .some u.seful sample code which does something similar. 
It is available at most Macintosh archives, but its home is on 
Jim Luther’s curiously ftp-ba.sed web page. 

Jim Luther 

<ftp://members.aol.com/jumpLong/index.html> 

These and rivers of other links are available from the 
.MacTech Online web pages at <http://www.mactech.com/online/>. 
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Want to know what products 
are available for Mac OS 
development? Check out 
Developer Depot® 
<http://www.devdepot.com> 
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3 REALbasic 

Visit www.realbasic.com for a FREE 30 day trial version 
or call (512) 292-9988 for more information 


Modern Object-Oriented BASIC 
Full native compilation 
PowerPC Shared Library Support 
Imports VB Forms and Code 
Appearance Manager Savvy 
XCMD, AppleEvents and AppleScript Support 
Built-in Sprite Animation Engine 
...Windows and Java Compilers on the way! 


REALbasic is a trademark of REAL Software, Inc. 


























iCybe^ 


YouriOne^top shopifdral^ 
^ your developer needs! ^ 


PO Box 5200 • Wesdake Village, CA • 91359-5200 
Voice: 800/MACDEV-l (800/622-3381) • Outside HS/Canada: 805/494-9797 
Fax: 805/494-9798 • E-mail: ordcrs@>devdepotcom / 





Professkmal Software Developers 

Looking for c^eer opportunities? 
Check out our website! 

Nationwide Service 
Employment Assistance 
Resume Help 
Marketability Assessment 
Never a fee 

Scientific Placement, Inc. 

800-231 -5920 800-757-9003 (Fax) 

das @ scienti fic.com 



Try a RISK FREE subscription and see for 
yourself — at the low price of only 
$19.95 for six issues. 


Phone: 800/622-3381 

Outside us/Canada: 805/494-9797 

Fax: 805/494-9798 

E-mail: orders@netprolive,^(:om 

www.netprolive.com 


administrators look for answers. Each issue provides you with 
practical and detailed solutions for real world problems, 
extensive how-to articles, in-depth product reviews, practical 
tutorials, tips, techniques, reliable technology 
summaries, and more! a 


PROFESSIONAL 
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HERE AND NOW! 

MACWORLD Expo/San Francisco 

Exhibits: January 5-8,1999 
Workshops: January 4,1999 

Macworld/Pro Conference: 

January 5-7,1999 

MACWORLD Users Conference: 

January 6-8,1999 


Francisco, CA 


For millions of computer users, Macintosh is synonymous with 
increased productivity and innovative technology advances. 
Come to San Francisco—home to a “think different” community 
—for the latest technologies and trends that will change the way 
you work, play and learn now and in the future. 


At MACWORLD Expo/San Francisco, youMl demo, touch, see 
and feel all the hot new products—from more than 400 leading 
vendors. Learn time-saving productivity secrets through in-depth 
workshops, advanced and user-level conference programs. Hear 
from the brightest stars who are shaping the future of the Mac 
universe at the much-anticipated keynote address. 


MACWORLD Expo/San Francisco has the latest solutions for: 


the Internet 

digital content creation, 
management and delivery 

multimedia 
software development 
small business 


• r^emote worker programs 

• connectivity 

• graphic design 

• publishing 

• education, research 
and development 


Take advantage of money-saving specials when you buy 
products right on the show floor. 


Owned & Produced by: 


mlDG 

WORLD EXPO 


Sponsored by: 

Maiiuorlil 


Managed by: 

#IDG 


EXPO 


Discover what the future holds at 
MACWORLD Expo/San Francisco. 
Register to attend todayl 


VISIT: www.macworldexpo.com 

c^800-645-EXPO 


Yes! Please send me more information about 
MACWORLD Expo/San Francisco! I'm interested in: 

□ Attending □Exhibiting IMTI 


Name 

Tille_ 


Company. 

Address 


City/State/Zip_ 
Phone_ 


Fax. 


email- 


Of you would like to receive information via email about MACWORLD txfx)) 

Mail to: MACWORLD Expo, 1400 Providence Highway, 

P.O. Box 9127, Norwood, MA 02062. Or Fax to: 781-440-0357 

THIS IS NOT A REGISTRATION FORM. 
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by Jeff elites <online@mactecb.com> 


AinrOCOMPLETION IN MPW 

One very useful feature of many Unix shells is that you only 
need to type the beginning of a command, hit tab, and it fills in 
the complete command. I was really missing this on MPW, 
especially with long command names such as 
UnobsoleteNameRe visions. 

So here's a script that attempts to provide this feaaire in 
MPW, as well as possible. Bind it to Command-Tab (or whatever 
you want), then type “nam”, hit Command-Tab, and watch it fill 
in “NameRevisions” for you. 

Note: if nothing is selected, it will try to complete the last 
word on the current line. If you want to complete a word in the 
middle of a line, you’ll have to select it. 

If is in your {Commands} variable, it will also consider all 
files in the current directory, as I have found no way to figure 
out whether a file is an MPW script or not. Actually, this may 
even be useful. 

# gel ihe currcni selection 

Set CurrentSelection “'Catenate “{Active 

If “ICurrentSelectionl“ = ““ 

* select the entire line we’re on 
Find !0 “(Active}” 

* put the insertion point at the beginning of this line 
Find A§:A§ “(Active!” 

^ remember line number, .so we can restore it later 
Set CurrentLine 'Position -1 "(Active! 

« select the last word on this line 

Find /["• 9t9n] + [ dt] •»/ “(Active!” || (Beep; Exit 0) 

* if it isn’t really on our current line, exit 

If 'Position '1 “(Active)"' != (CurrentLine) 

Find (CurrentLine! “(Active}” 

Beep 
Exit 0 
End 

Set CurrentSelection “'Catenate “(Active)“ 

* strip spaces fix)m the end, if any 

If “(CurrentSelection)" /(h ^tl-l-)®l[ dt]*/ 

Set CurrentSelection "(®1)" 

End 

* can this happen at this point? 

If "(CurrentSelection!” = “” 

Beep 
Exit 0 
End 
End 

^ a list of matching command names 
Set CommandList “” 

# the number of matches found 
Set Matches 0 

# first see if it’s one of the built-in commands 
^ (we really have to list them all here, sigh...) 

For 1 In () 

AddMcnu AddPane Adjust Alert Alias Align AuthorInfo 3 
Beep Begin Break Browser Catenate Checkin Checkout d 


CheckOutDir Clear Close Confirm Continue Copy Cut Date 3 
Delete DeleteMenu DeleteNames DeletePane 3 
DeleteRevisions Directory Duplicate 3 
DuplicateMameRevisions Echo Eject Equal Erase Evaluate 3 
Execute Exists Exit Export Files Find Flush 3 
FlushAllVolumes For Format Help HideWindows If 3 
LockNameRevisions Loop Mark Markers ModifyReadOnly 3 
Monitors Mount MountProject Move MoveWindow 3 
NameRevisions New Newer NewFolder NewProject 3 
ObsoleteNameRevisions ObsoleteProjectorFile Open 3 
Parameters Paste PlaySound Position Project Projectinfo 3 
Quit Quote Redo Rename RenameProjectorFile Replace 3 
Request ResolveAlias Revert RotatePanes RotateWindows 3 
RProj RShell Save SaveOnClose Set SetFile SetKey Shift 3 
ShowSelection ShowWindows Shutdown SizeWindow 3 
StackWindows Target TickCount TileWindows Unalias Undo 3 
Unexport UnlockNameRevisions Unmark Unmount 3 
UnmoimtProject UnobsoleteNameRevisions 3 
UnObsoleteProjectorFile Unset UnsetKey 3 
UpdateProjectorDatabase Version Volumes Which Windows 3 
ZoomWindow 

If “(i)" =~ /(CurrentSelection)*/ 

Set CommandList "(CommandList) (i)" 

Evaluate Matches += 1 

End 

End 

# now pn)cess every folder in the current {Commands} list 
For Folder in 'Which' 

For File In 'Files “(Folder}" -s' 

* append all matching names to our list of command names 
If "(File)" /(CurrentSelection)*/ 

Set CommandList "{{CommandList}) MFile)*" 

Evaluate Matches += 1 

End 

End 

End 

^ no matching names found 
If {Matches} = 0 

Find /W “(Active)" 

Exit 0 
End 

# if more than one name was found, present a list 

# to choose from 

If {Matches! > 1 

Set CommandList “'GetListItem -sort -s -c {CommandList)'" 

Exit 0 If “{CommandList}" ” "" 

Else If "{CommandList}" / (*)®l/ 

* if only one name was found, it has a space at the 

# beginning; strip it. And remove any unnece.ssary 

^ quoting. 

Set CommandList "'Quote {®1)'” 

End 

replace the selection with the found (or chostm) name 
Echo n “(CommandList} “ > “(Active 1".§ 

Find §A “(Active)” 

Stefan Haller 
<stk@snafu.de> 
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How much do you pay 
for network consultation? 



Get Your FREE Personal 
Network Consultation 
with Dr. Farallon 


At absolutely no cost Dr. Farallon's network experts can help you. 


"For free, a Dr. Farallon 
Network Specialist analyzed 
our existing system, identi¬ 
fied a range of options, and 
helped us plan and install a 
network with the speed and 
capacity we need at a price 
we could afford." 


%/ Implement switching to optimize your current network 

✓ Upgrade your Macs, PCs, servers & printers to Ethernet or Fast Ethernet 

✓ Integrate lOBase-T & 100Base-T with 10/100 hubs & switches 

✓ Budget for network improvements & plan for network growth 

Call: 1 - 800 - 613-4954 

Visit: www.farallon.com/dr.farallon/mactech.html 



Irene Ogus, CEO, 
Media Corps 
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In today’s exploding digital publishing market, 
experienced professionals are hard to find. In fact, 
they’re downright scarce. So whether you’ve got a 
job to fill or are looking for a job, look no further. 

Introducing eMediaweekly Careers. A new 

editorial section in eMediaweekly devoted to 
current hiring trends, training issues, salary levels, 
recruitment, and the do’s and don’ts of hiring. 
eMediaweekly is the ONLY magazine to bring 
these issues to the forefront in the fast-growing 
digital publishing industry. 

Advertising Opportunities 

eMediaweekly Careers provides a unique advertising 
opportunity for companies in search of skilled 
professionals in content creation. Whether you’re 



searching for that talented graphic designer or that 
anal-retentive production director, eMediaweekly 
Careers is the perfect place for you. Only in 
eMediaweekly Careers can you place your ad 
amidst relevant editorial for the best positioning. 

And only eMediaweekly delivers a core group of 
75,000 digital media professionals. 

For further information on how you can make use 
of this invaluable resource, contact Jennifer 
Bonwell at 415.243.3680 (East Coast) or 
Eric Moore at 415.278.8553 (West Coast). 

Can Only Be Found In 

<• eMediaweekly» 

The Newsweekly for Digital Media Managers 
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